We use git branches to manage our software. These notes show how we merge and manage branches to release updates to our software.

The PyFBA project shows how to use branches to maintain different code bases for development and public release. We have three branches in our code:

1. The master branch. This is the source of the current stable version of the code, and you should download this. It is not the latest version, but all tests have passed.
2. The working branch. This is the current potentially unstable branch, and you should not use this unless you are a developer. This is where all the new code is submitted.
3. The gh-pages branch. This is a specific branch that handles the websites that are displayed at the PyFBA website. You should not edit anything in this branch as the documents are automatically created from the Makefile in the master/working branches.

We edit code in the working branch. To make life easier, we also have an empty file called WORKING in that branch that tells us we are in the working branch. It is just a simple visual check.

Before you start, we recommend that you include a few automatic hooks into your software:

• Travis Continuous Integration is a great way to ensure that everything builds. We highly recommend setting this up for your code.
• Zenodo will allow you to create DOIs associated with software releases. A terrific way to ensure that your work is citable.

Once you are done editing the code and ready to update the release, there are several steps that we need to take.

1. In the working branch, make sure that all your tests pass:

nosetests PyFBA/tests/

1. If your tests don’t pass, do not continue to step 2! Fix the problem, and repeat until they do pass.
2. Increase the release version number in PyFBA/init.py and VERSION. We use incremental numbers, but we should probably come up with release 1.0 (or 2.0) soon. We keep the version in two places so that it is obvious, but try and keep them in sync!
3. Edit CHANGES.md and add the changes that you have made since the last release. You should have already done this as you were making the changes, but make sure it is up to date.

If you want to know which files have changed, used git diff:

git diff --name-only master

And then to get the changes for an individual file:

git diff working master -- PyFBA/fba/run_fba.py

Note that the CHANGES.md file should not contain a list of the diffs, that is why we have versioning. It should contain notes about why the changes were made or the issues they resolved.

1. Convert the CHANGES.md to CHANGES.txt using pandoc:

pandoc -f markdown_github -t plain -o CHANGES.txt CHANGES.md

1. Commit any outstanding changes and push them to the GitHub repo. (You can’t continue to step 7 unless you do that!)
2. Switch to the master branch

git checkout master

1. Merge with the working branch

git merge working

Note: if there are any conflicts reported here, you will need to resolve them before you can proceed. Resolve them by editing the files and using git add to put the edited files in the master branch.

If the merge copied the WORKING file over to the master branch, just delete it (using git rm) and commit that change. It is an empty file, and just there for convenience.

1. Push the code

git push

1. Build the new release for PyPi

python setup.py sdist upload

Make sure that this ends with the message: Server response (200): OK

1. At this stage it is a good idea to update your local installation using pip:

pip install --upgrade PyFBA

1. Make the new version of the documentation and publish it. In the master branch of the git repo, you can just issue the command:

make gh-pages

This will make the documentation, publish it, and bring you back to the working branch of the repo. Note that this does not return you to the master branch.

1. If you made any changes to the master branch, you need to merge those back to the working branch, so that you can keep editing things. Note that this may or may not delete the WORKING file. If it is deleted just add it back.