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, check pyramid_oereb. 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
  

• Delete the pyramid_oereb docker volume, if present, in order to start with a clean setup:

  • docker volume rm pyramid_oereb_venvs
    

• Check that the json, xml and pdf generations are functional by starting a local development server:

  1. docker network create print-network
     

  2. Depending on your OS do:
     • Linux:

       docker compose run --rm -u $(id -u):$(id -g) oereb-make build
       

     • MAC/Windows:

       docker compose run --rm oereb-make build
       

  3. Execute

     docker compose up
     

     Sometimes the local postgres port is already in use, and you must override it:

     EXPOSED_PGPORT=5433 docker compose up
     

  4. Check the xml and json generation:
     • http://localhost:6543/oereb/extract/xml?EGRID=CH113928077734
     • http://localhost:6543/oereb/extract/json?EGRID=CH113928077734
  5. To check the pdf generation, you additionally need a running instance of the https://github.com/openoereb/pyramid_oereb_mfp project:
     • Clone the https://github.com/openoereb/pyramid_oereb_mfp repository
     • Navigate to the root directory of the pyramid_oereb_mfp project and execute:

       make serve
       

     • Check http://localhost:6543/oereb/extract/pdf?EGRID=CH113928077734
• Update migration notes (file doc/source/changes.rst), if applicable, and edit the changelog (file CHANGES.rst)
• Do a

  make doc-html
  

  and check quality of doc (copy absolute path of the file pyramid_oereb/doc/build/html/index.html into your browser)
• Do a

  make check
  

• Check that the package description is OK (and will be accepted by pypi.org) as follows:
  • Make sure python3-pip is installed:

    • python3 -m ensurepip --upgrade
      

  • Make sure you have the latest version of PyPA’s build installed:

    • python3 -m pip install --upgrade build
      

  • Build local packages:
    • Navigate to the directory where pyproject.toml is located
    • Execute

      python3 -m build
      

  • Make sure twine is installed in a current version:

    • python3 -m pip install --user --upgrade twine
      

  • 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 pyproject.toml 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 pyproject.toml.
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/