Versioning

Versioning scheme

This project follows the semantic versioning scheme with one exception: Instead of three version numbers (MAJOR.MINOR.PATCH), we use four version numbers (MAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH). Note that this is compliant with PEP 440 which allows an arbitrary number of version numbers.

Given a version number MAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH, we increment the

  • MAJOR-CORE version when we make backwards-incompatible changes in the MDTools core package.

  • MAJOR-SCRIPTS version when we make backwards-incompatible changes in one or more MDTools scripts.

  • MINOR version when we add functionality in a backwards-compatible manner (either in the core package or in scripts; this includes the release of a completely new script).

  • PATCH version when we make backwards-compatible bug fixes (either in the core package or in scripts; this includes pure documentation updates or pure dependency updates).

Pure code refactoring or project maintenance work that does not affect how users interact with this project (i.e. the core package and the scripts) does not lead to a version increase.

If a preceding version number is increased, all following version numbers must be reset to zero. For instance, if we make a backwards-incompatible change of the command-line interface of a script in version 1.3.2.1, the version must be updated to 1.4.0.0.

Pre-release, post-release and developmental release specifiers can be appended to the version number with a hyphen in accordance to PEP 440, e.g. 1.3.2.0-dev2.

Note

As long as the MAJOR-CORE and MAJOR-SCRIPTS number is 0 (i.e. the API and UI have not stabilized), even MINOR increases may introduce incompatible API or UI changes.

Publishing a new release

Note

New versions can only be released by project maintainers that have write access to the upstream repository.

Follow these steps when publishing a new release.

1. Update the version number

Create a new branch out of main named chore/release/vMAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH.

git checkout main
git checkout -b chore/release/vMAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH

Update AUTHORS.rst to list all authors that have contributed to the new release and commit the changes to the new branch.

Add authors that have contributed for the first time to the CITATION.cf file and to the list of authors in the _metadata module of MDTools (src/mdtools/_metadata.py) and commit the changes to the new branch.

Update the version number __version__ in the version module (src/mdtools/version.py) of MDTools to the new MAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH version and commit the changes to the new branch.

Push the branch to the upstream repository.

git push --set-upstream origin chore/release/vMAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH

Open the upstream repository in GitHub, create a pull request and merge the branch into main when all tests passed successfully.

Pull the changes to your remote repository.

git checkout main
git pull

2. Create a new tag

On the main branch, create a new tag that contains the new MAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH version number prefixed with a “v”:

git tag -a vMAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH

As tag message enter:

MDTools version MAJOR-CORE.MAJOR-SCRIPTS.MINOR.PATCH

Release notes at https://github.com/andthum/mdtools/releases

Push the tag to the upstream repository.

Important

First push, then push --tags!

git push
git push --tags

3. Create a new release

Open the upstream repository in GitHub and follow the steps outlined in the GitHub doc page Creating automatically generated release notes for a new release. When selecting a tag, use the tag you just created in the previous step. Carefully check the automatically generated release notes and make changes if necessary.