Contribution Workflow

The following steps are done for each recipe or batch of recipes you’d like to contribute.

1. Create a Branch

Next, we create a “branch”. You could in theory work on the master branch, but it helps if you give the work you are intending to do a name. That way you can more easily work on separate issues if one of them turns out to be more complicated than you thought.

# Make sure our master is up to date with Bioconda
git checkout master
git pull upstream master
git push origin master

# Create and checkout a new branch for our work
git checkout -b update_my_recipe

2. Add a Recipe or Make Some Edits

Now you need to add your files or make your edits. Naturally, this can become rather complex.

Typically this involves creating within a in recipes/ two files:

  • A meta.yaml recipe file

  • A (optional) build.sh script.

For more detailed guides, see the the following tutorials

However for some fast tips: if you have a PyPi recipe you want to package for Bioconda, you could start with the conda skeleton command creating a template automatically:

cd recipes
conda skeleton pypi pyaml

(pyaml is just an example. It would not be included in Bioconda as it is a general purpose package. Those need to be added to conda-forge, where pyaml is already present.)

Now edit the file(s) in the newly created folder (named according to the package).

If you can’t use a skeleton, copy from other recipes written in the same language as your tool.

You can verify your edits by looking at the diff:

git diff

Or, you can have a look at the changed files and status of your repository using status:

git status

You can also at this point do a local build to test that the recipe will work correctly. See Testing Recipes Locally or if you have problems, see the following tutorial: Debugging a Bioconda build - a reference guide

3. Push Changes

To publish your changes, “add” them, then “commit” all added changes, then push the branch to GitHub:

# Choose the edited files to commit:
git add pyaml
# Create a commit (will open editor)
git commit
# Push your commit to GitHub
git push

4. Create a Pull Request

Now head back to GitHub. Go to your fork of the bioconda-recipes repository and find the branch you have just created in the Branch: drop down. You should now see a message saying This branch is 1 commit ahead [...] bioconda:master. To the right of that line you will find a button Pull Request. Click this and follow the instructions to open a new Pull Request.

If you get stuck, have a look at GitHub’s own About Pull Requests documentation.

Once you have opened a PR, our build system will start testing your changes. The recipes you have added or modified will be linted and built. Unless you are very lucky, you will encounter some errors during the build you will have to fix. Repeat 2. Add a Recipe or Make Some Edits and 3. Push Changes as often as needed.

Eventually, your build will “turn green”. If you are a member of Bioconda, you can now add the please review & merge label to submit your PR for review. Otherwise, just ask on Gitter or ping @bioconda/core.

Once you changes have been approved, they will be “merged” into our main repository and the altered packages uploaded to our channel.

5. Delete your Branch

Once the Pull Request has been merged, you can click Delete Branch directly on GitHub, or you can remove the branch with git:

# Delete local branch
git branch -D my_branch
# Delete branch in your fork via the remote named "origin"
git push origin -d my_branch

6. Install Your Package

After the Pull Request has been merged, you will need to wait for a little while for the package to become available. Our channel is so popular that Anaconda decided to give us the “CDN treatment”. While this makes downloads faster, it means that updates to the Bioconda channel take approximately a half hour to propagate. Once this has happened, you can enjoy:

conda install my-package