Batphone Git development branch

The development branch of the Batphone Git repository is used to prepare the next public release of Serval Mesh.

Serval developers generally commit to the development branch while working between releases, observing the committing rules below.

Rules for committing

The head of the development branch can only be advanced by senior developers:

  • a senior developer commits onto the development branch and pushes to GitHub:
    • small-scale push conflicts (few commits) are resolved using git pull --rebase (see example below), to keep the Git branch history linear
    • large-scale push conflicts (many commits) are resolved using git pull (see example below), which creates an explicit merge between the two divergent lines of development
  • a senior developer merges a feature branch or a contributor's branch into the development branch and pushes to GitHub:
    • the merge should be performed with the --no-ff option to force a new commit to be created (ie, avoid a fast-forward)
    • the merge commit's author identifies which senior developer performed the merge; may be different from the author of the branch
    • the senior developer may annotate the merge commit with extra comments that were lacking in the branch's history
  • a senior developer merges the Batphone Git master branch into the development branch when concluding a release:
    • the merge should be performed with the --no-ff option to force a new commit to be created (ie, avoid a fast-forward)
    • the resulting merge commit must be tagged with as pre-release for the next release version (see below)

Every commit on the development branch should:

  • have a descriptive commit comment that references any and all relevant GitHub issues,
  • build cleanly (no compiler errors or warnings), and
  • pass all automated tests.

Pre-release tags

Some commits on the development branch are tagged as pre-release candidates, which have names of the form version_number –pre [ pre_number ], eg, 0.95-pre or 1.0-pre2. Every such pre-release candidate tag must be annotated, otherwise the Git describe command will not produce the correct result.

The following Git command performed in an up-to-date Git clone of the Batphone repository will list all the pre-release candidate tags and the first lines of their annotations:

$ git tag --list -n1 | egrep '^[0-9]+\.[0-9]+-pre[0-9]*\s'
...
0.91-pre        0.91-pre
0.91-pre2       0.91-pre2
0.92-pre        Set new version for unstable builds
0.92-pre2       Merge branch 'origin/master' into development
...
$

Examples for committing

Push without conflicts

A senior developer makes some changes, commits them onto the development branch in a private clone of the Batphone repository and pushes the new commits to GitHub, which advances the development HEAD:

$ vi README.md src/org/servalproject/Main.java
$ git status --short
 M README.md
 M src/org/servalproject/Main.java
$ git add .
$ git status --short
M  README.md
M  src/org/servalproject/Main.java
$ git commit -m 'Change donations link'
$ git push --quiet
$
Push with conflicts

Two senior developers, Alice and Bob, each commit different changes onto the branch in their own private clones of the Batphone repository. Alice pushes her new commits to GitHub, which advances the development HEAD (see example above). Bob attempts to push, but this fails because his commits are no longer based on the HEAD of the branch:

bob$ vi README.md CURRENT-RELEASE.md res/values/warning_strings.xml
bob$ git status --short
 M CURRENT-RELEASE.md
 M README.md
 M res/values/warning_strings.xml
bob$ git add .
bob$ git status --short
M  CURRENT-RELEASE.md
M  README.md
M  res/values/warning_strings.xml
bob$ git commit -m 'Update warning disclaimers'
bob$ git push --quiet
To git@github.com:servalproject/batphone
 ! [rejected]        development -> development (non-fast-forward)
error: failed to push some refs to 'git@github.com:servalproject/batphone'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
bob$

To rectify this problem, Bob must fetch Alice's changes from GitHub, merge them with his own, and push the result. For small-scale changes (involving relatively few commits), this should be done using the git pull --rebase command:

bob$ git pull --rebase
remote: Counting objects: 13, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 7 (delta 4), reused 0 (delta 0)
Unpacking objects: 100% (7/7), done.
From git@github.com:servalproject/batphone
 + 5beb7b2...6258f5f development -> origin/development  (forced update)
First, rewinding head to replay your work on top of it...
Applying: Update warning disclaimers
bob$ git push --quiet
bob$

Login