HOW_TO_RELEASE.md

Procedure to release a new version of Argopy

Argopy follows semantic versioning with a Major.Minor.Patch / X.Y.Z pattern.

We try to implement the following policy:

• Increase Patch for bug fixes and existing feature improvements (deprecation cycle not affected).
• Increase Minor to highlight one important new feature, a batch of feature improvements, enforce deprecation policy.
• Increase Major for significant refactoring, change in API facade or to highlight software/team milestone.

Current versions of Argopy distributed with pypi and conda are:

How to release a Patch version

Setup

Don't change X Major and Y Minor, increase Z Patch only.

• Create a new branch for this release: git checkout -b releasevX.Y.Z
• Update release version in ./docs/whats-new.rst
• Increase release version in ./setup.py
• Create a PR to prepare it, copy/paste this section to the PR description.
• Activate RTD build for this branch

Prepare code for release

Deprecation policy

Does not apply for Patch release. Only consider deprecation policy for Major or Minor releases.

Update static content

• Update static asset files using the CLI update_json_assets command.
• Update the cheatsheet PDF with all new release features, if any.

Code clean-up and update

• Run codespell from repo root and fix errors: codespell -q 2
• Run flake8 from repo root and fix errors

Software distribution readiness

• Possibly update ./requirements.txt and ./docs/requirements.txt if this Patch release requires a change in dependencies version to fix a bug.
• Make sure that all CI tests are passed:
• Make sure the documentation for this release branch is built on RTD:

Preparation conclusion

• Merge this PR to master
• Update release date in ./docs/whats-new.rst
• Verify that all CI tests are passed
• Verify that RTD doc is built on the master branch

Publish the release

• Last check the ./setup.py file version of the release and that the documentation is ready
• "Create a new release" on GitHub. Choose a release tag vX.Y.Z, fill in the release title and click on the Auto-generate release notes button. Once ready, publish the release. This will trigger the publish Github action that will push the release on Pypi.
• Checkout on Pypi and Conda that the new release is distributed.

How to release Major or Minor versions

For a Major: increase X Major, reset Y Minor and Z Patch to 0 (eg: v2.0.0).

For a Minor: don't change X Major, increase Y Minor only, reset Z Patch to 0 (eg: v1.3.0).

Setup

• Create a new branch for this release: git checkout -b releasevX.Y.Z
• Update release version in ./docs/whats-new.rst
• Increase release version in ./setup.py
• Create a PR to prepare it, copy/paste this section to the PR description.
• Activate RTD build for this branch

Prepare code for release

Deprecation policy

• Check the code for the deprecated decorator and enforce the deprecation policy:
  • If code is marked as deprecated since version = vX.Y.Z : do nothing (first version with deprecation warning)
  • If code is marked as deprecated since version = vX.(Y-1).Z : do nothing (2nd and last version with deprecation warning)
  • If code is marked as deprecated since version = vX.(Y-2).Z : delete code (code will raise an error)
• Update the documentation file whats-new.rst section Internals of this release with the list of class/methods that have been deleted.

Update static content

CI tests data

• Update CI tests data used by mocked ftp and http servers. Use the CLI citests_httpdata_manager:

  cd cli
  ./citests_httpdata_manager -a clear --force --refresh
  ./citests_httpdata_manager -a download
  ./citests_httpdata_manager -a check

Library static assets

• Update static asset files using the CLI update_json_assets command:

  cd cli
  ./update_json_assets

• Update cheatsheet PDF with all new release features.

Code clean-up and update

• Run codespell from repo root and fix errors: codespell -q 2
• Run flake8 from repo root and fix errors

Software distribution readiness

• Possibly update ./requirements.txt and ./docs/requirements.txt if the dependencies versions were upgraded for a bug fix or new feature.
• Make sure that all CI tests are passed:
• Make sure the documentation for this release branch is built on RTD:

Preparation conclusion

• Merge this PR to master
• Update release date in ./docs/whats-new.rst
• Verify that all CI tests are passed
• Verify that RTD doc is built on the master branch

Publish the release

• Last check the ./setup.py file version of the release and that the documentation is ready
• "Create a new release" on GitHub. Choose a release tag vX.Y.Z, fill in the release title and click on the Auto-generate release notes button. Once ready, publish the release. This will trigger the publish Github action that will push the release on Pypi.
• Checkout on Pypi and Conda that the new release is distributed (this can take 2/3 days for conda).