Release Philosophy

This section discusses topics related to Tardigrade-examples releases and version numbering.

Version Numbers

The Tardigrade-examples project follows the PEP-440 standard for version numbering. The production release version number uses the three component (“major.minor.micro”) scheme. The developer (a.k.a. dev) version number follows the production release number with an appended “.dev” local version number. The version numbers correspond to git tags in the upstream repository which point to a static release of the Tardigrade-examples project.

Because the deployed release of the developer version is constantly updated against development work, the version number found in the developer version contains additional information. During deployment, the developer version number is appended with the git information from the most recent build. This information contains the most recent git tag (“major.minor.micro+dev”) followed by the number of commits since the last production release and a short hash.

Major Number

The major number is expected to increment infrequently. After the first major release, it is recommended that the major version number only increments for major breaking changes.

Minor Number

The minor number is updated for the following reasons:

New features
Major internal implementation changes
Non-breaking interface updates

Incrementing the minor version requires a manual update to the release number found in the Git tags on a dedicated release commit. Until the first major release, minor version changes may also contain breaking changes. It is recommended that all minor version changes are announced to the user community prior to release.

Micro Number

The micro number is automatically incremented after any merge from the development (dev) branch into the production (main) branch. The micro version number indicates the following changes:

Bug fixes
Minor internal implementation changes

Until the first major release, micro version number releases may be made without announcement at the discretion of the lead developer. It is recommended that the developer community periodically discuss priorities for minor version release with the user community.

Release Branch Requirements

All production releases require a release branch. Releases correspond to a variety of bug fixes and features that characterize the release, as documented in Changelog.

The following steps will trigger a micro bump. Major and minor version bumps require a manual Git tag update for the otherwise automated setuptools_scm SCM version.

Steps needed for a release include:

Create a release branch.
Modify docs/changelog.rst to move version number for release MR commit, add a description as relevant, and update any missing entries in the changelog.
Commit changes and submit a merge request to the dev branch at the upstream repository.
Major and Minor bumps ONLY: Create a new developer version tag, e.g. ?.?.0+dev, on the new commit. Reset all numbers to the right of the bump to 0, e.g. 1.2.3 becomes 2.0.0+dev for a Major version bump or 1.3.0+dev for a Minor version bump.
```
$ git tag 1.7.0+dev
```

Push release branch with the new tag

$ git push origin <release branch name>
$ git push --tags

Submit a merge request to the dev branch of the upstream repository.
Immediately submit a dev->main MR after merging the release branch to dev.
Review tests and notes, receive approval, and merge to main.