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

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

Source Code

Step 1

Make sure the source builds and works locally, and the docs build with no errors

Step 2

Make sure the source passes GitHub Actions CI

Step 3

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 'pin dependencies' wis2box-management/Dockerfile
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

Step 4

Publish Docker packages

• Update DockerHub

  • TODO: WMO to add

• Update GitHub Container Registry

ghcr.io/wmo-im/wis2box-management

cd wis2box-management/
docker build --no-cache -t wis2box-management:local .  # note SHA
docker tag $SHA ghcr.io/wmo-im/wis2box-management:x.y.z
docker image push ghcr.io/wmo-im/wis2box-management:x.y.z

ghcr.io/wmo-im/wis2box-api

git clone https://github.com/wmo-im/wis2box-api.git
cd wis2box-api
vi wis2box_api/__init__.py  # update __version__
git commit -m '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
docker build --no-cache -t wis2box-api:local .  # note SHA
docker tag $SHA ghcr.io/wmo-im/wis2box-api:x.y.z
docker image push ghcr.io/wmo-im/wis2box-api:x.y.z
cd ..

ghcr.io/wmo-im/wis2box-auth

git clone https://github.com/wmo-im/wis2box-auth.git
cd wis2box-auth
vi wis2box_auth/__init__.py  # update __version__
git commit -m '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
docker build --no-cache -t wis2box-auth:local .  # note SHA
docker tag $SHA ghcr.io/wmo-im/wis2box-auth:x.y.z
docker image push ghcr.io/wmo-im/wis2box-auth:x.y.z
cd ..

ghcr.io/wmo-im/wis2box-broker

cd wis2box-broker
docker build --no-cache -t wis2box-broker:local .  # note SHA
docker tag $SHA ghcr.io/wmo-im/wis2box-broker:x.y.z
docker image push ghcr.io/wmo-im/wis2box-broker:x.y.z
cd ..

ghcr.io/wmo-im/wis2box-mqtt-metrics-collector

cd wis2box-mqtt-metrics-collector
docker build --no-cache -t wis2box-mqtt-metrics-collector:local .  # note SHA
docker tag $SHA ghcr.io/wmo-im/wis2box-mqtt-metrics-collector:x.y.z
docker image push ghcr.io/wmo-im/wis2box-mqtt-metrics-collector:x.y.z
cd ..

• Ensure all packages continue to be publicly available at https://github.com/orgs/wmo-im/packages)

Step 6

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

mkdir -p asset/wis2box-x.y.z
vi docker-compose.yml  # change all containers with to their tagged and built equivalent on GHCR
vi docker-compose.monitoring.yml  # change all containers to their tagged and built equivalent on GHCR
# copy required docker configs and env file bootstrap
cp docker-compose.monitoring.yml docker-compose.wis2box-ftp.yml docker-compose.data-subscriber.yml docker-compose.override.yml docker-compose.ssl.yml docker-compose.yml asset/wis2box-x.y.z
cp -rp nginx prometheus loki grafana asset/wis2box-x.y.z
cp wis2box-ctl.py wis2box-create-config.py asset/wis2box-x.y.z
# discard local changes
git checkout docker-compose.yml docker-compose.monitoring.yml
cd asset
# create README
cat << EOF > wis2box-x.y.z/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-x.y.z

Keep the resulting wis2box-setup-x.y.z.zip for Step 8.

Step 7

Update demo server: TBD

Step 8

Create a release on GitHub.

• Go to https://github.com/wmo-im/wis2box/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 wis2box-setup-x.y.z.zip (from Step 6) as part of the release announcement
• 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
  • 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