Git Conventions

This describes various conventions and the reasons behind them, concerning use of GIT.

Branch naming

master

This is the main branch where things are merged into, and from time to time, releases are made from.

Some project may have multiple branches e.g., master and master-v2. These typically reflect on-going versions being developed together.

branches for working

Work is typically done in a branch. This because the master(s) are protected, which means they cannot be "pushed" to, but rather, a change must be pulled from a branch via a pull request.

Exception: trivial changes, or changes not needing review. These can be made on the master, which corresponds to how we worked in SVN. Depending on the particular Repository protection scheme, committers may be able to push to the branch without a pull-request.

Branches for working are typically named using the Jira issue (if there is one) associated with the work, followed by a very-short-description - enough to remind you what that jira number is about. In addition, the name can be prefixed with the kind of work it is, e.g. feature/ or bugfix or refactor. This can be useful in enabling you to more rapidly locate the right branch.

After merging into master, the branch is typically deleted.

Branches for releasing

When you are about to make a release, you typically will create a branch for the release; this branch will be checked out and the maven release prepare / perform will run on it, and in the process create commits to the branch updating the various "versions", first by removing the -SNAPSHOT, and then by updating them to the next SNAPSHOT version.

The maven release prepare/perform operations include "pushing" to the remote.

The branches used for the release work are typically named rc/uimaXXXXX-x.y.z. (rc stands for Release Candidate). See git-release-notes.hmtl.

Commit messages

Example: [UIMA-1234] summary-of-Jira summary-of-change

Git has a two-section commit message. The first line should be a one-line id with summaries. Following that is an optional section of multiple lines that can have more details about the commit.

The first line should start with the jira issue number including UIMA- prefix. Automatic scanners use this to connect this to the Jira issue. You may put multiple issues if applicable. The issues may be written with surrounding square brackets, e.g. [UIMA-1234].

Following that should be short title of the issue, since looking back at it a reader probably won't remember what the issue was all about. Following that can be a summary of what this particular commit does.