Development model

This project follows the Feature-Branching model. Briefly, there are two main GitHub branches: master and develop. The former contains the history of stable releases, the latter contains the history of development. The master branch contains checkout points for production hotfixes or merge points for release-x.x.x branches. The develop branch is used for feature-bugfix integration and checkout point in development. Nobody should directly develop in here.

Conventions

To manage the project in a more consistent way, here is a list of conventions to follow:

  • Each new feature is developed in a separate branch forked from develop. This new branch is called featureNUMBER, where NUMBER is the number of the GitHub Issue discussing that feature. The first line of each commit message for this branch should contain the string Issue #NUMBER at the beginning. Doing so, the commit is automatically recorded by the Issue Tracking System for that specific Issue. Note that the sharp (#) symbol is required.
  • The same for each new bugfix, but in this case the branch name is called bugfixNUMBER.
  • The same for each new hotfix, but in this case the branch name is called hotfixNUMBER and is forked from master.

Work flow

The procedure for checking out a new feature from the develop branch is:

git checkout -b feature10 develop

This creates the feature10 branch off develop. This feature10 is discussed in Issue #10 in GitHub. When you are ready to commit your work, run:

git commit -am "Issue #10, summary of the changes. Detailed
description of the changes, if any."
git push origin feature10       # sometimes and at the end.

As of June 2016, the branches master and develop are protected and a status check using Travis-CI must be performed before merging or pushing into these branches. This automatically forces a merge without fast-forward. In order to merge any new feature, bugfix or simple edits into master or develop, a developer must checkout a new branch and, once committed and pushed, merge it to master or develop using a pull request. To merge feature10 to develop, the pull request output will look like this in GitHub Pull Requests:

base:develop  compare:feature10   Able to merge. These branches can be
automatically merged.

A small discussion about feature10 should also be included to allow other users to understand the feature.

Finally delete the branch:

git branch -d feature10      # delete the branch feature10 (locally)

New releases

The script release.sh at the root of the package is used to release a new version of SBpipe on:

  • github
  • pypi
  • anaconda cloud (channel: pdp10)

Conda releases

This is a short guide for building a conda package for SBpipe. Miniconda3 and the conda package conda-build must be installed:

conda install conda-build

SBpipe is stored in two Anaconda Cloud channels:

  • bioconda (official)
  • pdp10 (for testing purposes only)

How to release the conda package of SBpipe on the bioconda channel (Anaconda Cloud)

This conda repository is used for storing the stable releases of SBpipe and sbpiper. More documentation can be found here:

The first step is to setup a repository forked from bioconda-recipes:

# fork the GitHub repository: https://github.com/bioconda/bioconda-recipes.git

# clone your forked bioconda-recipes repository
git clone https://github.com/YOUR_REPOSITORY/bioconda-recipes.git

# move to the repository
cd bioconda-recipes

# create and checkout new branch `sbpipe`. This branch is used for both sbpipe and sbpiper.
git checkout -b sbpipe

# set a new remote upstream repository that will be synced with the fork.
git remote add upstream https://github.com/bioconda/bioconda-recipes.git

# synchronise the remote upstream repository with your local forked repository.
git fetch upstream

Create the recipes for SBpipe and sbpiper:

# assuming your current location is bioconda-recipes/, move to recipes
cd recipes

# use conda skeleton to create a recipe for sbpipe.
# This will create a folder called sbpipe.
conda skeleton pypi sbpipe

# use conda skeleton to create a recipe for sbpiper.
# This will create a folder called r-sbpiper
conda skeleton cran sbpiper

################
### At this stage, follow the instructions provided in the above three links. ###
################

Finally, the recipes should be committed and pushed. A pull request including these edits should be created in the repository bioconda/bioconda-recipes

git add -u
git commit -m 'added recipes'
git push origin sbpipe

How to test the conda package of SBpipe on the pdp10 channel (Anaconda Cloud)

This channel is used for storing the latest release of SBpipe and sbpiper. It is also used by Travis-CI for continuous integration tests.

# DON'T FORGET TO SET THIS so that your built package is not uploaded automatically
conda config --set anaconda_upload no

The recipe for SBpipe is already prepared (file: meta.yaml). To create the conda package for SBpipe:

cd path/to/sbpipe
conda-build conda_recipe/meta.yaml -c pdp10 -c conda-forge -c fbergmann -c defaults

To test this package locally:

# install
conda install sbpipe --use-local

# uninstall
conda remove sbpipe

To upload the package to Anaconda Cloud repository:

anaconda upload ~/miniconda/conda-bld/noarch/sbpipe-x.x.x-py_y.tar.bz2

To install the package from Anaconda Cloud:

conda install sbpipe -c pdp10 -c conda-forge -c fbergmann -c defaults