Contributing to repo2docker¶
Thank you for thinking about contributing to repo2docker! This is an open source project that is developed and maintained entirely by volunteers. Your contribution is integral to the future of the project. THANK YOU!
Types of contribution¶
There are many ways to contribute to repo2docker:
Update the documentation. If you’re reading a page or docstring and it doesn’t make sense (or doesn’t exist!), please let us know by opening a bug report. It’s even more amazing if you can give us a suggested change.
Report a bug. If repo2docker isn’t doing what you thought it would do then open a bug report. That issue template will ask you a few questions described in more detail below.
Suggest a new feature. We know that there are lots of ways to extend repo2docker! If you’re interested in adding a feature then please open a feature request. That issue template will ask you a few questions described in detail below.
Review someone’s Pull Request. Whenever somebody proposes changes to the repo2docker codebase, the community reviews the changes, and provides feedback, edits, and suggestions. Check out the open pull requests and provide feedback that helps improve the PR and get it merged. Please keep your feedback positive and constructive!
Tell people about repo2docker. As we said above, repo2docker is built by and for its community. If you know anyone who would like to use repo2docker, please tell them about the project! You could give a talk about it, or run a demonstration. The sky is the limit :rocket::star2:.
Process for making a contribution¶
This outlines the process for getting changes to the repo2docker project merged.
Bug reports (examples, new issue) will ask you for a description of the problem, the expected behaviour, the actual behaviour, how to reproduce the problem, and your personal set up. Bugs can include problems with the documentation, or code not running as expected.
It is really important that you make it easy for the maintainers to reproduce the problem you’re having. This guide on creating a minimal, complete and verifiable example is a great place to start.
Feature requests (examples, new issue) will ask you for the proposed change, any alternatives that you have considered, a description of who would use this feature, and a best-guess of how much work it will take and what skills are required to accomplish.
Very easy feature requests might be updates to the documentation to clarify steps for new users. Harder feature requests may be to add new functionality to the project and will need more in depth discussion about who can complete and maintain the work.
Feature requests are a great opportunity for you to advocate for the use case you’re suggesting. They help others understand how much effort it would be to integrate the work,and - if you’re successful at convincing them that this effort is worth it - make it more likely that they to choose to work on it with you.
Open an issue. Getting consensus with the community is a great way to save time later.
Wait for a community member to merge your changes. Remember that someone else must merge your pull request. That goes for new contributors and long term maintainers alike. Because
masteris continuously deployed to mybinder.org it is essential that
masteris always in a deployable state.
(optional) Deploy a new version of repo2docker to mybinder.org by following these steps
Guidelines to getting a Pull Request merged¶
These are not hard rules to be enforced by 🚓 but they are suggestions written by the repo2docker maintainers to help complete your contribution as smoothly as possible for both you and for them.
Create a PR as early as possible, marking it with
[WIP]while you work on it. This avoids duplicated work, lets you get high level feedback on functionality or API changes, and/or helps find collaborators to work with you.
Keep your PR focused. The best PRs solve one problem. If you end up changing multiple things, please open separate PRs for the different conceptual changes.
Add tests to your code. PRs will not be merged if Travis is failing.
Apply PEP8 as much as possible, but not too much. If in doubt, ask.
Use merge commits instead of merge-by-squashing/-rebasing. This makes it easier to find all changes since the last deployment
git log --merges --pretty=format:"%h %<(10,trunc)%an %<(15)%ar %s" <deployed-revision>..and your PR easier to review.
Make it clear when your PR is ready for review. Prefix the title of your pull request (PR) with
[MRG]if the contribution is complete and should be subjected to a detailed review.
Use commit messages to describe why you are proposing the changes you are proposing.
Try to not rush changes (the definition of rush depends on how big your changes are). Remember that everyone in the repo2docker team is a volunteer and we can not (nor would we want to) control their time or interests. Wait patiently for a reviewer to merge the PR. (Remember that someone else must merge your PR, even if you have the admin rights to do so.)
Setting up for Local Development¶
To develop & test repo2docker locally, you need:
Familiarity with using a command line terminal
A computer running macOS / Linux
Some knowledge of git
At least python 3.6
Your favorite text editor
A recent version of Docker Community Edition
Clone the repository¶
First, you need to get a copy of the repo2docker git repository on your local disk. Fork the repository on GitHub, then clone it to your computer:
git clone https://github.com/<your-username>/repo2docker
This will clone repo2docker into a directory called
repo2docker. You can
make that your current directory with
Set up a local virtual environment¶
After cloning the repository, you should set up an isolated environment to install libraries required for running / developing repo2docker.
python3 -m venv . source bin/activate pip3 install -e . pip3 install -r dev-requirements.txt pip3 install -r docs/doc-requirements.txt pip3 install black
This should install all the libraries required for testing & running repo2docker!
black as code formatter to
get a consistent layout for all the code in this project. This makes reading
the code easier.
To format your code run
black . in the top-level directory of this repository.
Many editors have plugins that will automatically apply black as you edit files.
We also have a pre-commit hook setup that will check that code is formatted
according to black’s style guide. You can activate it with
As part of our continuous integration tests we will check that code is formatted properly and the tests will fail if this is not the case.
Verify that docker is installed and running¶
If you do not already have Docker, you should be able to download and install it for your operating system using the links from the official website. After you have installed it, you can verify that it is working by running the following commands:
It should output something like:
Client: Version: 17.09.0-ce API version: 1.32 Go version: go1.8.3 Git commit: afdb6d4 Built: Tue Sep 26 22:42:45 2017 OS/Arch: linux/amd64 Server: Version: 17.09.0-ce API version: 1.32 (minimum version 1.12) Go version: go1.8.3 Git commit: afdb6d4 Built: Tue Sep 26 22:41:24 2017 OS/Arch: linux/amd64 Experimental: false
Then you are good to go!
Building the documentation locally¶
If you only changed the documentation, you can also build the documentation locally using
pip install -r docs/doc-requirements.txt cd docs/ make html
Then open the file
docs/build/html/index.html in your browser.