The branching model used on this repo borrows heavily from the model outlined by the article A successful Git branching model and by the development process outlined by stan-dev, although there are some minor differences in the execution.

Main ideas:

• There are two permanent branches

  • The master branch reflects the last stable release of the product.
  • The development branch is where work is done

• Never push directly to master or development

  • Development of new features is done by creating a new branch from development, making your changes on that branch, then merging it back in to the development branch.
  • When you are ready for a new release, merge the changes from development into the master branch via a release branch.

Adding a new feature into the development branch

Make changes to the development branch by branching off of the development branch.

# Switch to development branch
git checkout development

# Pull changes to make sure you have the latest changes 
git pull

# Create a new branch from development called issue-x
git checkout -b issue-x

git push -u origin issue-x

The last git push command sets up a remote version of the new issue-x branch so that other people working on your code can see what you're doing.

A word about naming branches

As much as possible, name new branches after issues. For example, if something along the lines of dev/issue-6. This way, we can track who is working on what issue, we can more clearly lay out who is working on what files (minimizing merge conflicts), and we can more clearly lay out expectations.

It doesn't always make sense to name a branch after an issue. For example, if you're developing a new feature, or if you're hotfixing an issue. In the case of adding a new feature, I name the branch something like feature/new_feature. Hotfixing is a bit different, as will be explained in the next section.

Now that the new branch is set up, code and document as usual. After you have all your changes committed and your working directory is clean, run your unit tests. Then, still on your feature branch:

# Update your local development branch to most current version of development branch
git pull origin development

# Merge the updated development branch into your feature branch
git merge --no-ff development

At this point, handle any merge conflicts that may arise. If the project is well-coordinated and individual tasks are assigned in such a way as to minimize conflict, then there shouldn't be any merge conflicts arising at this point.

After resolving any merge conflicts, push your local version of the feature branch to the remote:

git push

This will push your changes to the remote branch.

The pull request

Now go to the repo on github.com and open a pull request. In the body of the pull request, put a link to the issue that you were working on, address the sections in the original pull request, and document how you tested the changes (in the future I will implement automated testing, either by Travis CI or github apps). Before you submit the pull request, make sure to switch the base branch to development.

At this point, an admin will verify the pull request. Verify that the pull request has development as the base branch. If not, you are able to change the base branch at this point. If everything looks good, accept the pull request, and delete the remote branch.

After a successful pull

After the feature branch is successfully pulled into the development branch, go back to your local and:

# Switch to development branch
git checkout development

# Get most updated version of the development branch
git pull

# Delete the feature branch
git branch -d issue-x

After all of this, you've successfully added code to the development branch.

Hotfixing an issue

Hotfixing an issue arises when a severe bug or error has been discovered in the program that needs to be repaired immediately. Hotfix branches branch off of the master branch and are merged into both the master and development branches.

Begin by making the new branch based off the master branch:

git checkout master
git pull 
git checkout -b hotfix-x
git push -u origin hotfix-x

I give the branch some short name describing the bug somehow. For instance, I recently fixed a bug in the mfpdesign program, so I just called the branch hotfix-mfpdesign.

From here, make the changes as usual, commit them all, make sure your working directory is clean, and run your tests. Then:

git checkout master

# Merge changes from hotfix into Master branch
git merge --no-ff hotfix-x

Now we merge the changes into the development branch so that the bugfix is included in future releases:

git checkout development
git merge --no-ff hotfix-x

Finally, remove the hotfix branch:

git branch -d hotfix-x

Pushing new releases

When you are ready to incorporate the changes of the development branch into your master branch, we push the changes from the development branch into the master branch via an intermediary release branch.

Begin by branching off of the development branch:

git checkout -b release-x development

(The naming convention that I'm using is that major releases are numbered 1, 2, etc., and minor releases are x.1, x.2, etc. Currently, MetaFunPrimer is in beta, so it's version 0, and patches, etc., bump up that version number to 0.1, 0.2, etc. The article that this model is based on suggests making a bump_version.sh script to automate the process of bumping the version number.)

The advantage of doing releases as a separate branch is that you can now take time to finish documentation, check for typos, rerun unit tests, etc., while allowing other developers to continue branching off of and making contributions to the development branch without fear of modifying the eventual release.

When you're ready to release, we begin by merging into the master branch:

git checkout master
git merge --no-ff release-x

Now that the master branch is updated to the current release, we'll now merge these changes into development branch:

git checkout development
git merge --no-ff release-x

All that is left to do is delete the release branch:

git branch -d release-x