Contributing to repo2docker development¶

Process for making a code contribution¶

This outlines the process for getting changes to the code of repo2docker merged.

If your change is relatively significant, open an issue to discuss before spending a lot of time writing code. Getting consensus with the community is a great way to save time later.
Make edits in your fork of the repo2docker repository
Submit a pull request (this is how all changes are made)
Edit the changelog by appending your feature / bug fix to the development version.
Wait for a community member to merge your changes
(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 :police_car: but instead guidelines to help you make the most effictive / efficient contribution.

prefix the title of your pull request with [MRG] if the contribution is complete and should be subjected to a detailed review;
create a PR as early as possible, marking it with [WIP] while you work on it (good to avoid duplicated work, get broad review of functionality or API, or seek collaborators);
a PR solves one problem (do not mix problems together in one PR) with the minimal set of changes;
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);
someone else has to merge your PR;
new code needs to come with a test;
apply PEP8 as much as possible, but not too much;
no merging if travis is red;
do 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>..

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 cd repo2docker.

Set up a local virtual environment¶

After cloning the repository (or your fork of the repository), you should set up an isolated environment to install libraries required for running / developing repo2docker.

There are many ways to do this but here we present you with two approaches: virtual environment or pipenv.

Using virtual environment

python3 -m venv .
source bin/activate
pip3 install -e .
pip3 install -r dev-requirements.txt
pip3 install -r docs/doc-requirements.txt

This should install all the libraries required for testing & running repo2docker!

Using pipenv

Note that you will need to install pipenv first using pip3 install pipenv. Then from the root directory of this project you can use the following commands:

pipenv install --dev

This should install both the dev and docs requirements at once!

Set up¶

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:

docker version

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!

On this page