Skip to content

Development

Jump to bottom
Alfio Lazzaro edited this page Aug 29, 2022 · 11 revisions

Development model

We are using the Git Flow branching model with rebased feature branches and GitHub Pull Requests (PR).

This means:

  • develop is our default & development branch. Developers can submit single, short commits directly here.
  • For larger changes, please use a feature/... branch (whether in your fork or on the DBCSR repo does not matter) and submit a PR for review.
  • Do a git rebase develop of your feature branch before submitting the Pull Request or merging.
  • Always do git pull --rebase to update your clone (or setup git to rebase by default by setting once git config --global pull.rebase true)
  • master is the release branch. Every merge here constitutes a new release.
  • Split your commits into reasonable junks (use git add -i) and squash fixes in your feature branch before merging or submitting a PR (use git rebase --interactive develop) .

Links to Git Flow:

Commit messages

  • keep the summary (first line) short (usually <=50 characters), possibly include a tag. Examples:

    travis: add required package lapack

libcusmm: add parameters for new Turing card

  • use proper references to existing issues in the bug tracker or keywords to automatically close issues in your commit messages

Release procedure

  • Release tagging happens on the master branch.
  • Therefore, directly after a release, add another merge from develop to master to establish a relationship between tags and commits on develop (the git-flow tools previously mentioned do that automatically when using the git flow release ... commands).

Walkthrough (manual)

The following assumes that you are in an up-to-date clone of dbcsr and that the remote pointing to https://github.com/cp2k/dbcsr is called upstream.

$ DBCSR_VERSION=X.Y.Z
$ git checkout -b release-${DBCSR_VERSION} develop  # create new release branch based on develop, when not using the tip of develop, use a hash instead of "develop"
$ $EDITOR VERSION  # update the version number and the release date
$ git commit -m "Bump version to ${DBCSR_VERSION}" VERSION
$ git checkout master
$ git merge --no-ff release-${DBCSR_VERSION}  # merge the release branch
$ git tag -a -m "Version ${DBCSR_VERSION}" v${DBCSR_VERSION}
$ git checkout develop
$ git merge --no-ff master  # merge the master into develop to ensure common ancestry
$ git remote add upstream [email protected]:cp2k/dbcsr.git
$ git push --atomic --follow-tags upstream master develop  # push the two branches
$ git branch -d release-${DBCSR_VERSION}

Walkthrough (with git-flow tools)

Using the git-flow tools, the process is a bit easier:

$ git flow release start X.Y.Z
$ $EDITOR VERSION  # update the version number
$ git commit -m "Bump version to X.Y.Z" VERSION
$ git flow release finish X.Y.Z
$ git push --atomic --follow-tags upstream master develop  # push the two branches

Release on GitHub

  • GitHub does a release on https://github.com/cp2k/dbcsr/releases for each tag
  • CI is setup to build a complete tarball including all submodules for each tag and upload it as a draft
  • After this is done, you have to update the release information for the release (update the changelog, etc.) and toggle the flag to mark is as a non-draft.

pre-commit hooks

We're using the https://pre-commit.com/ project to manage pre-commit hooks. Those hooks will also be executed by the CI, but it is highly recommended to enable them locally.

To install them you need Python and the pip command (usually already installed). To install the pre-commit command itself, use pip:

$ pip install pre-commit

you may have to specify the --user option if you get an error message for not having sufficient permissions.

Afterwards run the following once in your clone of DBCSR (if you clone again you have to run this command again, but not when switching or creating branches):

$ pre-commit install

Afterwards, git will automatically run all our required hooks on each commit on the files to be committed and refuse the commit if one or more of the checks failed.

Note: Some of the checks may also modify the files. If that happens you should check the changes using git diff and then use git add to incorporate them into your commit before trying git commit again.

Should you already have committed without the hooks and the CI complains about your commits, then run the following to check all files:

$ pre-commit run --all-files
Clone this wiki locally