How to develop with Git

From BlackBox Framework Wiki
Jump to navigation Jump to search

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.

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.

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.
Retrieved from "http://wiki.blackboxframework.org/index.php?title=How_to_develop_with_Git&oldid=186"