This guide is an equivalent to Zeek's own Release Process, specifically for the zkg package manager. The process is more straightforward that for Zeek itself, and this guide mainly serves as a checklist for new merge masters.

• Make sure you can build the documentation. You can test via make doc. You'll need Sphinx and its napoleon plugin, which you can install via pip install sphinxcontrib-napoleon.
• Install the twine toolchain.
• Make sure that everything you want to see released is merged into master and the testsuite passes. You only need to run update-changes (more on that below) when making a release.

The basic components to a release are

• an updated CHANGES file (zkg uses no NEWS file: CHANGES provides all release notes)
• a git version tag and matching VERSION file
• a push to PyPI to create a corresponding package release
• a submodule bump in Zeek

More specifically:

• A git commit "Updating CHANGES and VERSION" is the release-defining commit.
• This commit has a vX.Y.Z tag. (We no longer use a release tag.)
• The CHANGES file in this commit looks as follows (A.B.C is the version preceding X.Y.Z):

  X.Y.Z | <date & time>
  
    * Release X.Y.Z.
  
  A.B.C-n | <date & time>
  
    * ...
  

You can use the update-changes script from zeek-aux for the file/commit/tag management, as follows:

• Once you have merged the release features into master, run update-changes to summarize the updates in CHANGES.
• Run it again, but as update-changes -R vX.Y.Z. This updates CHANGES and VERSION via a new commit and establishes the git tags.
• Your commit layout and content should now be as desired.
• Do a git push and git push --tags.
• Create the release on PyPI:
  • 1Password has the login and password, and provides the authenticator token. You can use these in your ~/.pypirc for authentication, etc.
  • The Makefile has a target for the twine upload, just say: make upload. The versioning mechanism picks up the VERSION file content.
  • Check the zkg page on PyPI.
  • Do a pip install zkg to verify installation of the new version.
• Pull the aux/package-manager submodule in the Zeek repository up to the new zkg master. No need to request approval for this update.
• Done!

The docs need no extra handling to update after you created a release. We host them on readthedocs.io, and the updates happen via a webhook on the Github project that's configured to push on tag creation/deletion.

Use the semantic versioning guidelines. zkg releases have been happening fairly frequently; don't hesitate to make a release when new material has accumulated in master.

zkg's release versions are independent of Zeek. zkg gets released more frequently than Zeek. Keep in mind that the zkg version bundled with Zeek will be the one seeing most use.

The repository has one release branch: release/1.7. Newer releases have happened on master. The 1.7 series predates Zeekification and no longer gets updates. Since zkg doesn't currently follow Zeek's release regimen (annual LTS releases, etc), there isn't one release branch per X.Y.* series.