Maintainer's Zone

From ESPResSo
Jump to: navigation, search


ESPResSo Versions

ESPResSo releases use a version number consisting of three numbers (e.g. 3.1.0):

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

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

Creating a Release

  • Check that NEWS are updated
  • Tag the release with the new version number (e.g. 3.3.0)
 git tag -s <version>
  • Push the tag to github
 git push --tags <github>
  • Tags are not automatically forwarded to savannah, so push them to savannah
 git push --tags <savannah>
  • Run bootstrap on the code to update the version in the build system. This is required only if you do not use configure --enable-maintainer-mode.
 cd <srcdir>
  • Generate tarball.
 cd <builddir>
 make dist dist-xz
  • Sign tarball
 gpg -b --use-agent <bla>.tar.gz
 gpg -b --use-agent <bla>.tar.xz
  • Upload NEWS, tarballs and signatures
 scp <files> 
  • Until the files pop up at the mirrors, it might take a while
  • Write mailing to espressomd-users and espressomd-devel
  • Write news to ESPResSo home page and Savannah(?)

Git Repository Layout

The official ESPResSo git repositories on Github and Savannah use the following layout.

Development Branch (aka "master")

The master branch is where new features are integrated into ESPResSo and that ESPResSo developers should use as basis for their own developments. It should always contain the latest ESPResSo 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. 3.1). The actual releases are tagged within this branch (tag 3.1.0). 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.

Merging Commits


Bugfixes have to be pulled into the latest release branch. From there they can be easily put into the master branch.

  • Pull the commits into the release branch.
  • Update NEWS.
  • Merge the commits into the master branch
 git checkout master
 git merge <release-branch>
  • Push the commits to github
 git push <github>
  • If a bugfix commit has been committed to the master branch, you need to cherry-pick the commit
 git cherry-pick <commitid>

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 ESPResSo do contain the copyright and GPL headers, and whether the copyright header contains the current year.

 bash maintainer/

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

 bash maintainer/

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

 bash maintainer/

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 apt-get upgrade jenkins
  • There is also a user jenkins on the web server
  • The homedir is /var/lib/jenkins, 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 .ssh/authorized_keys

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 /scratch/jenkins
  • The home dir /home/jenkins 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.