Git Workflow

This memo presents the workflow we try to follow in Audiveris development on top of a Git distributed version control system.

This small work in progress is meant for any new contributor. And for us as well, it can be used as a memory help! 😏

Workflow

We recommend to read the Atlassian Tutorial, entitled "Comparing Workflows", which explains very clearly 4 different Git workflows.

For Audiveris, we have chosen among these 4 Git workflows the one named Gitflow Workflow. What follows is a summary for Audiveris users, please refer to Gitflow Workflow for the original detailed presentation.

It is best depicted by the following diagram stolen from Atlassian web site (the minor difference is that we prefer "development" branch rather than "develop").

This approach makes a heavy use of short-living branches (for features, releases, hotfixes) off of two permanent branches: master and development.

• Permanent branches:

1. The master branch stores the official release history. No development is done there. All commits in master are tagged with a version number.

2. The development branch serves as an integration branch for features.

• Temporary branches:

1. Any new feature is developed in a separate feature branch, named as the feature, created off of the development branch. Any feature branch will eventually be merged into the development branch and then deleted.

2. At key points in development process, a release branch, named as the release, is created off of the development branch, to hold the release preparation work. When the release is ready, the release branch is merged into both master and development branches. The master is tagged with the precise release number. The branch is then deleted.

3. To quickly patch production releases, a hotfix branch properly named can be created off of the master branch. When completed, it must be merged into both master and development, and the master should be tagged with an updated version number. The branch is then deleted.

Main Git commands

Feature

a/ To start a feature

(Assuming "basic-ui" is the name for this feature):

git checkout -b basic-ui development
git push -u origin basic-ui

b/ To complete the feature

git checkout development
git merge basic-ui
git push

c/ To delete the branch (local)

git branch -d basic-ui

d/ To delete the branch (remote)

git push origin --delete basic-ui

Release

a/ To start a release

(Assuming "release-5.0" is the name for this release):

git checkout -b release-5.0 development

b/ To complete the release

1/ Merge with master:

git checkout master
git merge release-5.0
git push

2/ Merge with development:

git checkout development
git merge release-5.0
git push

3/ Delete the release branch:

git branch -d release-5.0

c/ To tag a release

(Using a tag like "5.0"):

git tag -a 5.0 -m "Small description for the release" master
git push --tags

Hotfix

a/ To start a hotfix

(Assuming "export-npe" is the name for the hotfix):

git checkout master
git checkout -b export-npe

b/ To complete a hotfix

git checkout master
git merge export-npe
git push

git checkout development
git merge export-npe
git push

git branch -d export-npe

c/ To tag a hotfix

(Using a tag like "5.0.1"):

git tag -a 5.0.1 -m "Small description for the hotfix" master
git push --tags

Other Git commands we found useful

To pull and merge with local commits

In current branch, save local commits apart, pull remote commits if any, then merge with local ones

git pull --rebase

To make git ignore chmod changes

git config --global core.filemode false

To restore to initial state of development branch

git checkout development
git reset --hard origin/development