How to develop with Git

Topic Branches

For every issue entered into the redmine issue tracker we create a branch from 'master'.

If an issue has number N, we name that newly created branch issue-#N (see also 'Notes on Naming'). We work on the issue and discuss the solution within this topic branch.

When we agree that an issue has been solved, we create a so-called 'pull request' and merge that pull request into 'master'.

Multiple such topic branches can be worked on in parallel. For every branch you can see the files that are affected by this issue only. There is no mixing with changes that refer to other issues.

In order to reduce merge conflicts as much as possible, care should be taken not to work on conflicting issues in parallel but sequentially. A merge conflict arises if two topic branches modify the same binary .odc file or modify the same lines of an ASCII text file. If a merge conflicts arises, it must be resolved manually before merging a pull request.

Bi-Directional Traceability

The general rule with respect to committing changes to Git is to always refer to an issue in the commit message. The format of a commit message that refers to issue number N is

<commit message text>. Refs: #N.

When browsing the source code repository or when looking at commits (alias revisions) in redmine, references to issues will show up as links that can be clicked on. Similarly, when browsing the issues list in redmine, commits (alias revisions) that reference an issue show up as links that can be clicked on. Thereby you can always go from an issue to the related commits and from a commit to the related issue.

This feature is usually called bi-directional traceability and is a requirement in any standardized software engineering process. It is also used by many open source projects.

Please note the terminating dot after the referenced issue number in the commit message format. Its purpose it to serve together with the opening # as a bracket for issue numbers. With such a bracket you can search textually for a referenced issue by specifying a search string "#N." without mixing up the result with issues that happen to contain the same sequence of digits. For example, searching for "#2." should find only issue 2 but not issues 20, 21, 22, etc.

Building Unstable Releases

The build engine detects commits to all branches and starts the build process automatically. If the build engine detects an AppVersion.txt file with a development stage postfix, it builds an unstable release.

The output of the build process will be available in a subdirectory of http://blackboxframework.org/unstable named after the branch the build has been performed for.

Building Stable Releases

If the build engine detects an AppVersion.txt file with no development stage postfix, it builds a stable (final) release automatically.

The output of the build process will be available in http://blackboxframework.org/stable. The build output is supposed to be never changed later on without setting a new version number in AppVersion.txt.

For a final release X.Y, a tag named vX.Y should be inserted into the Git repository. In GitHub, a tag is added by creating a so-called release. The tag should be targeted at the master branch, which is used for creating final releases.

Notes on Naming

There are many ways of naming a topic branch. The simplest approach is to use only the issue number.

In an early experiment with a BlackBox issue a longer branch name has been used that also contained the subject of the topic. But this turned out to be a mistake because

• it leads to long branch names
• it may trigger an endless discussion about the 'best' name
• the name turned out to be inappropriate but cannot be changed later on.

Notes on Learning Git

The best source for learning the concepts and commands of Git is the Git book available under [1]. It has been translated into many languages and explains the basic concepts and the command line syntax of Git very well. Even if you use a graphical front end for Git, such as TortoiseGit or GitGUI, it is a valuable source for understanding Git because the many options and commands presented in any of the available graphical front ends can only be mastered if the basics of Git are clear.