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.