Release Philosophy

This section discusses topics related to WAVES releases and version numbering.

Version Numbers

The WAVES project follows the PEP-440 standard for version numbering. The production release version number uses the three component (“major.minor.micro”) scheme. The development 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 WAVES 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 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 version requires a manual update to the release number on a dedicated release commit. Versions are built from Git tags for the otherwise automated setuptools_scm version number tool. Tags may be added directly to a commit on the main branch, but a release branch is encouraged.

Steps needed for a release include:

  1. Create a release branch, e.g. release-0-4-1.

  2. Modify docs/changelog.rst to move version number for release MR commit and add description as relevant.

  3. Check and update the CITATION.bib, CITATION.cff, and waves/modsim_template/docs/references.bib file to use the new version number and release date.

  4. Commit changes and submit a merge request to the main branch at the upstream repository.

  5. Solicit feedback and make any required changes.

  6. Immediately prior to merge, add the new version tag to the most recent commit.

    $ git tag 0.4.1
$ git push origin release-0-4-1 --tags

  7. Merge the release branch to main

  8. Create a new release for the new tag: https://re-git.lanl.gov/aea/python-projects/waves/-/releases