👾 🎉 Thank you for contributing to the project! 🎉 👾
The following is a set of guidelines for contributing to binderhub-deploy on GitHub.
These are mostly guidelines, not rules.
Use your best judgement and feel free to propose changes to this document in a Pull Request.
Table of Contents
- 💜 Code of Conduct
- ❓ What should I know before I get started?
- 🎁 How can I contribute?
- 🎨 Styleguides
- 📓 Additional Notes
This project and everyone participating in it is expected to abide by and uphold the Code of Conduct. Please report any unacceptable behaviour to [email protected].
binderhub-deploy is a package designed to automatically deploy a BinderHub to Azure.
BinderHub is a cloud-based, multi-server platform for sharing reproducible computational environments using a Jupyter interface. @sgibson91 has given many talks one what Binder/BinderHub/mybinder.org is and how it works. This repository is recommended for those who wish to automate the deployment of their own, private BinderHubs.
This tool is based on bash scripts, information about which can be found in the Usage section of the README.
This repository contains a Dockerfile that can be built to run the tool. It also serves as a back-end to the "Deploy to Azure" button.
The built image of this file is hosted at: hub.docker.com/repository/docker/sgibson91/binderhub-setup.
The main branch is automatically built and tagged as latest whereas GitHub releases and tags are given the matching image tag.
When running the image, the parameters defined in template-config.json would be passed as environment variables.
The Deploy to Azure button serves as a graphical user interface to the Docker image that passes information as environment variables at runtime.
The configuration of the button parameters and variables is stored in the azure.deploy.json file.
This repository uses Continuous Integration tests to check for breaking changes and formatting within the code base. This repository has the following tests:
- Travis: This pipeline runs a matrix job to test that
setup.shcan run on Linux, OSX, and Windows platforms - Shellcheck and format: This GitHub Action workflow tests for formatting and linting of the shell scripts. It runs on the default branch and in Pull Requests and will leave comments on PRs if the test breaks.
- YAML formatting: This GitHub Action workflow check that the YAML templates throughout the repository are well-formatted and readable to prevent errors running the scripts.
If something doesn't work the way you expect it to, please check it hasn't already been reported in the repository's issue tracker.
Bug reports should have the bug label, or have a title beginning with [BUG].
If you can't find an issue already reporting your bug, then please feel free to open a new issue. This repository has a bug report template to help you be as descriptive as possible so we can squash that bug! 💪
If there was something extra you wish binderhub-deploy could do, please check that the feature hasn't already been requested in the project's issue tracker.
Feature requests should have the enhancement label.
Please also check the closed issues to make sure the feature has not already been requested but the project maintainers decided against developing it.
If you find an open issue describing the feature you wish for, you can "+1" the issue by giving a thumbs up reaction on the top comment of the issue. You may also leave any thoughts or offers for support as new comments on the issue.
If you don't find an issue describing your feature, please open a feature request. This repository has a feature request template to help you map out the feature you'd like.
Unsure where to start contributing? Check out the good first issue and help wanted labels to see where the project is looking for input. Spelling corrections and clarifications to documentation are also always welcome!
A Pull Request is a means for people to collaboratively review and work on changes before they are introduced into the base branch of the code base.
To prepare your contribution for review, please follow these steps:
- Fork this repository
- Create a new branch on your fork
- Where possible and appropriate, please use the following convention when naming your branch:
<type>/<issue-number>/<short-description>. For example, if your contribution is fixing a a typo that was flagged in issue number 11, your branch name would be as follows:fix/11/typo.
- Where possible and appropriate, please use the following convention when naming your branch:
- Edit files or add new ones!
- Open your Pull Request
- This repository has a pull request template which will help you summarise your contribution and help reviewers know where to focus their feedback. Please complete it where possible and appropriate.
Congratulations! 🎉
You are now a binderhub-deploy developer! 👾
The project maintainers will then review your Pull Request and may ask for some changes. Once you and the maintainers are happy, your contribution will be merged!
This repository uses all-contributors to acknowledge the time and expertise of the people who have made this tool into what it is today. Specifically, all-contributors has an emoji key to show the breadth of expertise required for a project like this.
This repository implements bash linting and formatting via shellcheck and shfmt.
These checks are run in a GitHub Action and will leave comments on Pull Requests if issues are found.
This will help us maintain readable code for future contributors.
Documentation files are written in Markdown.
When writing Markdown, it is recommended to start a new sentence on a new line and define a new paragraph by leaving a single blank line. (Check out the raw version of this file for an example!) While the sentences will render as a single paragraph; when suggestions are made on Pull Requests, the GitHub User Interface will only highlight the affected sentence - not the whole paragraph. This makes reviews much easier to read!
Issues and Pull Requests can have labels assigned to them which indicate at a glance what aspects of the project they describe. It is also possible to sort issues by label making it easier to track down specific issues. Below is a table with the currently used labels in the repository.
| Label | Description |
|---|---|
 |
Relating to the Azure deployment |
 |
Something isn't working |
 |
Relating to Continuous Integration workflows |
 |
Relating to the Dockerfile or image |
 |
Edits or improvements to the documentation |
 |
New feature or request |
 |
Good for newcomers |
 |
Relating to deploying Helm charts |
 |
Extra attention is needed |
 |
Related to deploying Kubernetes |
 |
Related to running on Linux |
 |
Related to managing the project |
 |
Related to running on MacOS |
 |
Related to running on Windows |