ReleaseManagement

The following are step-by-step instructions on how to package a wis2box release.

Building the Release Packages

Upstream packages

Step 1

Ensure upstream packages are tagged/release as required.

Package name	Release tag	Package indexes	Container registries	Notes
csv2bufr	x	PyPI		https://github.com/wmo-im/csv2bufr#releasing
bufr2geojson	x			https://github.com/wmo-im/bufr2geojson#releasing
pymetdecoder	x			https://github.com/wmo-im/pymetdecoder
synop2bufr	x			https://github.com/wmo-im/synop2bufr#releasing
pyoscar	x	PyPI		https://github.com/wmo-cop/pyoscar#releasing
pywcmp	x	PyPI		https://github.com/wmo-im/pywcmp#releasing
pywis-pubsub	x	PyPI		https://github.com/wmo-im/pywis-pubsub#releasing
pywis-topics	x	PyPI		https://github.com/wmo-im/pywis-topics#releasing
wis2box-api	x		ghcr.io	https://github.com/wmo-im/wis2box-api#releasing
wis2box-ui	x		ghcr.io	https://github.com/wmo-im/wis2box-ui#releasing
wis2box-webapp	x		ghcr.io	https://github.com/wmo-im/wis2box-webapp#releasing
wis2box-auth	x		ghcr.io	https://github.com/wmo-im/wis2box-auth#releasing

• Remember the versions, which will be used later on in the release process

Source Code

Make sure the source passes GitHub Actions CI.

Create tag

wis2box follows the Semantic Versioning Specification (SemVer).

Create a release tag against main:

wis2box

• update desired branch with x.y.z in
  • wis2box-management/wis2box/__init__.py (__version__)
  • docs/source/user/setup.rst
• commit the above updates:

# in branch main
git commit -m 'update release version x.y.z' wis2box-management/wis2box/__init__.py docs/source/user/setup.rst
git push origin main  # or branch if releasing from a branch

Release tags are in the format x.y.z

If releasing from main:

git tag -a x.y.z -m 'tagging release x.y.z'
git push --tags

If releasing from a branch:

git checkout x.y
git tag -a x.y.z -m 'tagging release x.y.z'
git push --tags

Update wis2box-release

Update https://github.com/wmo-im/wis2box-release/blob/main/docker-compose.images.yml to reflect the releases of the images that will comprise the wis2box release.

git commit -am 'update release version x.y.z'
git push origin main
git tag -a x.y.z -m 'tagging release version x.y.z'
git push --tags

Create release bundle

Create release asset bundle (default configuration and docker-compose setup files)

mkdir -p asset/wis2box-x.y.z
echo "x.y" > asset/wis2box/VERSION.txt
# copy required docker configs and env file bootstrap
cp docker-compose.monitoring.yml docker-compose.data-subscriber.yml docker-compose.override.yml docker-compose.ssl.yml docker-compose.yml asset/wis2box
cp -rp nginx prometheus loki grafana asset/wis2box
cp wis2box-ctl.py wis2box-create-config.py asset/wis2box
cd asset
# create README
cat << EOF > wis2box/README.txt
wis2box setup
=============

Please see https://docs.wis2box.wis.wmo.int/en/x.y.z/user/setup.html for setting up wis2box from example configurations in this directory.
EOF

# create zipfile for upload to release.
zip -r wis2box-setup-x.y.z.zip wis2box

Save the resulting wis2box-setup-x.y.z.zip locally.

Test the local zipfile

Before proceeding with the next step make sure to test the new release archive

Checklist for testing:

• Check new install using release archive by following instructions in the User guide
• Create a data notification using the new release and check x.y.z correctly reported in "generated_by": "wis2box x.y.z"
• Install previous release, create dataset, then check update is working using "python3 wis2box-ctl.py update --restart"
• Note any additional commands required to update wis2box from wis2box-release for the migration instructions

Create GitHub Release

Create a release on GitHub.

• Go to https://github.com/wmo-im/wis2box-release/releases
• Click 'Draft a new release'
• Under 'Tag Version' add the relevant release tag (x.y.z)
• Release title should be x.y.z
• Release description should be:
  • major or minor releases: wis2box x.y.z has been released. See the [release announcement](URL) for more information.
    • URL should be a link to the announcement made on wis2box Discussions
  • patch/bugfix releases: wis2box x.y.z has been released. This release is a maintenance/bugfix release.
• upload the following files as part of the release announcement
  • wis2box-setup-x.y.z.zip (from Step 6)
  • docker-compose.images.yml from https://github.com/World-Meteorological-Organization/wis2box-release/blob/x.y.z/docker-compose.images.yml
• Click "Set as a pre-release"
• Click "Publish release" (not "Save draft")
• (Validate the release)
• Ensure 'Create a discussion for this release' is checked to also publish to GitHub Discussions
• Click 'Publish release'
• Go to https://github.com/wmo-im/wis2box/discussions
• Rename the release from 'x.y.z' to 'wis2box x.y.z released'

Step 9

• Update default version in documentation/Read the Docs
  • Update https://readthedocs.org/dashboard/wis2box/advanced/ so that "Default version" points to the the release
    • only do this once the release has been fully validated
  • Click "Save"

Step 10

• Post release announcement to wis2box GitHub Discussions
• Tweet release
• TODO: other communication channels?

Step 11

• Update version in main back to dev (x.y.dev0)
• wis2box-management/wisbox/__init__.py
• git commit -am 'back to dev'
• git push origin main