RELEASE.md

Release instructions

Before creating a new release please do a careful consideration about the version number for the new release. We are following Semantic Versioning and PEP440.

Preparing the Required Python Packages

• Install twine for pypi package uploads and update poetry

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

Configuring the Access to the Python Package Index (PyPI)

Note: This is only necessary for users performing the release process for the first time.

• Create an account at Test PyPI.

• Create an account at PyPI.

• Create a pypi configuration file ~/.pypirc with the following content (Note: <username> must be replaced):

  [distutils]
  index-servers =
      pypi
      testpypi
  
  [pypi]
  username = <username>
  
  [testpypi]
  repository = https://test.pypi.org/legacy/
  username = <username>
  

Prepare testing the Release

• Fetch upstream changes and create release branch

  git fetch upstream
  git checkout -b create-new-release upstream/master

• Get the current version number

  poetry run python -m pontos.version show

• Update the version number to some alpha version e.g.

  poetry run python -m pontos.version update 1.2.3a1

Uploading to the PyPI Test Instance

• Create a source and wheel distribution:

  rm -rf dist build gvm_tools.egg-info
  poetry build

• Upload the archives in dist to Test PyPI:

  twine upload -r testpypi dist/*

• Check if the package is available at https://test.pypi.org/project/gvm-tools.

Testing the Uploaded Package

• Create a test directory:

  mkdir gvm-tools-install-test
  cd gvm-tools-install-test
  python3 -m venv test-env
  source test-env/bin/activate
  pip install -U pip  # ensure the environment uses a recent version of pip
  pip install --pre -I --extra-index-url https://test.pypi.org/simple/ gvm-tools

• Check install version with a Python script:

  python3 -c "from gvmtools.__version__ import __version__; print(__version__)"

• Remove test environment:

  deactivate
  cd ..
  rm -rf gvm-tools-install-test

Prepare the Release

• Determine new release version number

  If the output is something like 1.2.3.dev1 or 1.2.3a1, the new version should be 1.2.3.

• Update to new version number (<new-version> must be replaced by the version from the last step)

  cd path/to/git/clone/of/gvm-tools
  poetry run python -m pontos.version update <new-version>

• Update the CHANGELOG.md file:

  • Change [unreleased] to new release version.
  • Add a release date.
  • Update reference to Github diff.
  • Remove empty sub sections like Deprecated.

• Create a git commit

  git add .
  git commit -m "Prepare release <version>"

Performing the Release on GitHub

• Create a pull request (PR) for the earlier commit:

  git push origin

  Open GitHub and create a PR against https://github.com/greenbone/gvm-tools.

• Ask another developer/maintainer to review and merge the PR.

• Once the PR is merged, update the local master branch:

  git fetch upstream
  git rebase upstream/master master

• Create a git tag:

  git tag v<version>

  Or even a tag signed with a personal GPG key:

  git tag --sign --message "Tagging the <version> release" v<version>

• Push changes and tag to Github:

  git push --tags upstream

Uploading to the 'real' PyPI

• Uploading to PyPI is done automatically by pushing a git tag via CircleCI

• Check if new version is available at https://pypi.org/project/gvm-tools.

Bumping master Branch to the Next Version

• Update to a Development Version

The next version should contain an incremented minor version and a dev suffix e.g. 2.3.0.dev1. For example, if the released version was 1.2.3, it should be changed to 1.3.0.dev1.

poetry run python -m pontos.version update <next-dev-version>

• Create a commit for the version bump:

  git add .
  git commit -m "Update version after <version> release"
  git push upstream

Announcing the Release

• Create a Github release:

  See https://help.github.com/articles/creating-releases/