How to develop with Git

Related Pages

Pages related to this topic are The BlackBox Versioning Strategy, Git and How to develop with Tortoise Git.

Topic Branches

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

A new branch is created by:

• Go to GitHub https://github.com/BlackBoxCenter/blackbox.
• Alternatively:
  1. Go to the Center page: https://forum.blackboxframework.org.
  2. Click on the top level yellow option "GitHub repository"
  3. Click on the large blue "blackbox" text in the center of the page.

• Use the drop-down on the left of the page "Branch: master ▼" to create the new branch.
  1. In the field with light grey text "Find or create a branch" type "issue-#N"
  2. Click in the blue area "Create branch: issue-#N from 'master'".

If you use your browser's search function to search for the drop-down menu, use the search string 'Branch:', i.e. without 'master' because this depends on the currently selected branch.

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.

If the Component Pascal Language is changed such that a feature still used in the source code of other BlackBox topic branches is removed, such a change must be merged to master after all topic branches that use this feature.

Bi-Directional Traceability

The general rule with respect to committing changes to Git is to always refer to an issue in the first line of the commit message.

The format of the first line of a commit message that refers to issue number N is

<commit message text>. Refs: #N.

Example commit message for issue-#121:

fix for a compiler warning regarding unreleased register AX. Refs: #121.
As proposed by luowy but slightly corrected.
The additional FreeHi must only be called when y.mode = Int64.

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

Before building a stable release, check the state of all issues belonging to that release in the redmine issue tracker. Also check if descriptions of the issues exist and if they are formatted appropriately. They should look well both in html and in the BlackBox changelist document.

If the build engine builds for the branch master and detects an AppVersion.txt file with no development stage postfix, it builds a stable (final) release automatically. The core of building a stable release therefore is to remove the development stage postfix from the file appbuild/AppVersion.txt and commit it to master.

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, a tag named vX 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. The tag name vX is also used as the release title. Download links should be added in the description. By creating a release, Github creates source code archives in two formats (zip and tar.gz) automatically.

Finally, the download page of the center's web site should be updated.

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. 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.

The starting point for working with Git from the command line is the clone command. If you want to work on issue <N>, use the following command for cloning the repository to your local machine.

git clone https://github.com/BlackBoxCenter/blackbox.git blackbox-<N> -b issue-#<N>

This command will create a new directory named blackbox-<N> with a clone of the repository. Option -b sets the current branch to issue-#<N>.

The starting point for working with Git with the GUI-based tool Tortoise Git is How to develop with Tortoise Git.