Maintainer's Zone

Versions
releases use a version number consisting of three numbers (e.g. ):
 * The major version is increased only when significant (and most probably incompatible) changes have occurred. Versions with common major version number should be downwards compatible.
 * The minor version is increased whenever a release contains new features. Releases with common major and minor version numbers should be upwards and downwards compatible.
 * The subminor version is increased when we create bugfix releases.

Creating the Release Branch
When a release is created, it should be done on a release branch. All bugfixes to a release should go to the release branch. To get these fixes into the master, merge the release branch into the master. Never merge the master into the release branch!

The latest release branch should always be built in Jenkins to ensure that it builds fine.

git branch  git tag -s  git push --tags 
 * Create the branch (e.g. 3.2)
 * Never merge the master into the release branch
 * Create a -dev-Tag (e.g. 3.3-dev to mark where it branched off
 * Push the branch and to github
 * Create Jenkins jobs to automatically build the release branch.

Creating a Release
git tag -s git push --tags git push --tags cd  ./bootstrap.sh  cd   /configure make dist dist-xz gpg -b --use-agent .tar.gz gpg -b --use-agent .tar.xz  scp olenz@dl.sv.nongnu.org:/releases/espressomd/
 * Check that NEWS are updated
 * Tag the release with the new version number (e.g. 3.3.0)
 * Push the tag to github
 * Tags are not automatically forwarded to savannah, so push them to savannah
 * Run bootstrap on the code to update the version in the build system. This is required only if you do not use.
 * Generate tarball.
 * Sign tarball
 * Upload NEWS, tarballs and signatures
 * Until the files pop up at the mirrors, it might take a while
 * Write mailing to  and
 * Write news to home page and Savannah(?)

Git Repository Layout
The official git repositories on Github and Savannah use the following layout.

Development Branch (aka "master")
The master branch is where new features are integrated into and that  developers should use as basis for their own developments. It should always contain the latest code.

Release Branches
Whenever a release is done, it will first be visible on a release branch. All bugfix releases with common major and minor version are derived from its release branch, which is named by the major and minor version (e.g. ). The actual releases are tagged within this branch (tag  ). To prepare a first release on a branch, it might be necessary to remove code of a feature that is not to be put into a release yet. After a first release has been created from a release branch, all further commits should be strictly bugfixes.

Topic Branches
All other branches are topic branches. They can be used to prerelease larger features and modifications to the code so that interested users and developers can test them already. It is recommended to developers that they also use topic branches in their repositories when developing larger features.

Bugfixes
Bugfixes have to be pulled into the latest release branch. From there they can be easily put into the master branch. git checkout master git merge  git push git cherry-pick
 * Pull the commits into the release branch.
 * Update NEWS.
 * Merge the commits into the master branch
 * Push the commits to github
 * If a bugfix commit has been committed to the master branch, you need to cherry-pick the commit

New Features
New features should be well integrated, properly documented and ideally provide a test case. When this is given, the feature can be pulled into the master branch.
 * Pull commits into the master branch.
 * If a feature consists of many commits, in particular merge commits from pulling the master branch, you have two alternatives.
 * Either ask the author to rebase his commits, if he has not already passed on his commits to other people.
 * Or consider to squash his commits into a single commit.
 * Add an item to NEWS.
 * Push the commits to github

Check Copyright/GPL headers
Sometimes we have to check whether all files in do contain the copyright and GPL headers, and whether the copyright header contains the current year.

bash maintainer/files_with_header.sh

outputs a list of files that should contain a Copyright/GPL header.

bash maintainer/find_missing_header.sh

outputs a list of files and whether or not they contain the required headers.

bash maintainer/update_header.sh

will update the copyright header and add a line with the current year.

On the Webserver

 * The Jenkins LTS server runs on the webserver (elk) from the Ubuntu package. It can be updatd on the web server via
 * There is also a user jenkins on the web server
 * The homedir is, where all the data of jenkins lives
 * The user has an ssh key that is authorized for the user jenkins on all other machines
 * To be able to log in as user jenkins, put your ssh-key into the

On the ICP System

 * The ICP system has a user jenkins
 * That user authorizes the key of the user jenkins on the webserver, so that the jenkins server can start the slaves
 * The slaves put their data in
 * The home dir  contains some stuff used by all nodes (e.g. MPICH)

git clone vs. clone workspace

 * The job master-fetch-bootstrap pulls the current master from github, then runs bootstrap and archives the workspace for the other jobs.
 * The other jobs clone this workspace to do their work.
 * For a while, the fetch job merely pulled from github and pushed to a repository in /home/jenkins. The other jobs then pulled from that repo. This didn't work out well. The local repo regularly became corrupt and caused lots of jobs to fail.