Do a new release

Doing a new release

• Official release
• Testing release

Doing an official release

Quality check

• Be sure to be working on master branch, and do git pull
• Check release number: Edit pyproject.toml -> check version number is target number
• If a new number is needed, choose a version number. To see which version was previously published, do pip search pyramid_oereb (or check on pypi.org). To see all versions that have been previously published, use the following trick: pip install pyramid_oereb==999
• Delete all local docker images and do a make clean-all
• Do a make serve locally and check that json, xml and pdf generation are functional:
  • http://localhost:6543/oereb/extract/reduced/xml/CH113928077734
  • http://localhost:6543/oereb/extract/reduced/json/CH113928077734
  • http://localhost:6543/oereb/extract/reduced/pdf/CH113928077734 (requires current running instance of https://github.com/openoereb/pyramid_oereb_mfp)
• Update migration notes (file doc/source/changes.rst), if applicable, and edit the changelog (file CHANGES.rst)
• Do a make doc, and check quality of doc (in local browser)
• Do a make checks
• Check that the package description is OK (and will be accepted by pypi.org) as follows:
  • Make sure python3-setuptools and python3-pip packages are installed. Then, make sure twine is installed in a current version with python3 -m pip install --user --upgrade twine
  • Create local packages with python3 setup.py sdist bdist_wheel
  • Run the check with python3 -m twine check dist/*
  • If you get an error with the .rst, you can use the Python package rstcheck to get a full list of issues.
• Commit doc changes; you can push them right away, unless you are unsure about some points, in which case you can go through the normal pull request process.

Set a version tag

• Check that you are on master branch and up-to-date.
• Choose a version number, beginning with “v” (for example v1.4.0) to be consistent with previous releases
• do git tag <version_number>; git push origin <version_number>
• Check that this tag setting triggers a release by GitHub Actions,
  • PyPI
  • Note that this may take some time (the release pushes are done by GitHub Actions, at the end of the CI of the latest push)

Increment version number in source

• Edit setup.py to increment version number (for new daily builds) and push right away, so that next daily builds have higher number

GitHub release notes

Set release notes in GitHub user interface:

• Click on Code, Releases, Draft a new release
• Choose the tag version you created for the release (see above)
• Choose a release title (see previous releases for examples) and click on "Publish release"

Mapfish Print templates release

If changes affected the Mapfish Print proxy, print configuration file, or the templates, create a new tag and release with the same name at openoereb/pyramid_oereb_mfp.

Community communication

If CI is clean and release is present on both platforms (pypi and dockerhub), communicate to the community -> this is handled via Project Steering Committee, send them an e-mail to inform them when everything OK

Troubleshooting

• If you need to re-do everything, delete the tag by doing git tag -d <version-number>; git push origin :refs/tags/<version-number>
• When re-doing things, careful, as it may trigger actually useless/confusing Travis CI jobs -> stop them manually, and keep only the one coming from the tag setting$

Doing a testing release

1. Register on https://test.pypi.org/ and confirm your email.
2. On your local source code, switch to the branch you would like to create a test release for, then choose a dev version number (like 1.2.3.dev1) in setup.py.
3. Build the project.
4. Follow instructions on https://packaging.python.org/tutorials/packaging-projects/. (Points "Generating distribution archives" and "Upload distribution archives"). On Ubuntu 18, you probably will need to do in addition this to avoid a keyring error: pip3 install --upgrade keyrings.alt.
5. Before uploading to test.pypi.org, check that the dist contains everything you want (check it in the console output when the dist is generated, or in the archive generated into the dist directory)

Now, to use the test version in a project:

1. Change the setup.py to use the version number of the test release,
2. Add the following to the pip install command in the Makefile of the project: --extra-index-url https://test.pypi.org/simple/