Skip to content

Release Process

Jump to bottom
Christian Kreibich edited this page Jan 7, 2025 · 58 revisions

See Release Cadence for the intended release schedule as well as explanation and visual representation of the versioning scheme.

Release Checklist

Follow all these steps to complete a Zeek release. The order of the steps can be approximate and sometimes you may want to reorder things depending on what you are doing (e.g. making a release candidate, feature release, patch release, etc.). Try to read the full process ahead and understand the entire state of how things should end up. Sometimes there are one-off things you need to do, or even discover along the way (like documentation changes, test updates, or other fixes). Generally, it can help to create your own checklist based on this summary and insert the novel, one-off tasks at the place where it makes most sense.

If this is your first time making a release, you might expect this to take at least a full day to get everything organized and pushed out, but with familiarity it can be closer to only a couple hours, especially for simple patch releases (good luck!).

  • For a patch release (X.Y.Z), verify that the release/X.Y branch passes CI: it runs automatically on every commit to the branch, just make sure there's no failures in the latest commit you intend to release.

  • Update Zeek’s NEWS with release notes. The file should contain the most important information about the new version, including a summary of major changes, especially incompatible ones. It should also point out the major changes in submodules. Also, if site/local.zeek has changed, point out how to adapt a previous one accordingly.

    For feature releases (X.Y.0) make sure to call out contributors, using "@"-tagging on their Github handles so Github links them in its rendering of release notes.

    For patch releases, you can typically copy directly from the information tracked in https://github.com/zeek/zeek/issues/724 and use it as the release notes in NEWS.

    If there's security fixes involved in the release, you can add their descriptions and draw attention to them. (e.g. list them in a distinct "security fixes" section that comes before other non-security bugfixes)

  • Make sure that mozilla-ca-list.zeek and ct-list.zeek (in scripts/base/protocols/ssl/) have recently been updated. To update mozilla-ca-list.zeek, download the most recent release of NSS from https://ftp.mozilla.org/pub/security/nss/releases/, extract certdata.txt, and run auxil/zeek-aux/devel-tools/gen-mozilla-ca-list.rb on it. Update the "Generated from:" line in the generated file with the version of NSS that was used. To update ct-list.zeek, run auxil/zeek-aux/devel-tools/gen-ct-list.pl.

  • Finalize and make releases for all git submodules before their parent git repo to ensure the parent's submodule points at the correct version. If a submodule has no changes since the last Zeek release, you don't necessarily need to make a new release for it (e.g. happens often when making a X.Y.Z patch release). For any submodule that does need a new release, they each may have their own release process nuances, but generally:

    $ cd <into/submodule>
$ update-changes -R v1.2.3
$ make dist
$ # Sanity check the resulting tarfile
$ git push && git push --tags

    Note:

    If doing a Release Candidate for Zeek, you can skip this step since
submodules may change during the release candidate testing cycle.
Submodule releases can be completed once the testing cycle is done and
the final Zeek release is being built.

    Note:

    It's usually best to use the version of ``update-changes`` linked from
Zeek's ``master`` branch, not whatever is in the release branch as the
former may include bug fixes that aren't in the release yet (e.g. if
those bugs were discovered in the process of making a previous release).

The ``update-changes`` script can be also re-run for the same version if
you make last minute tweaks and it will delete the old tags and create new
ones, but you should only do that if the version hasn't been pushed yet.

    Note:

    If pushing tags warns of ``release`` already existing, you can delete it and
push again like ``git push --delete origin release && git push --tags``.
But, in Zeek's case, also think think first what the tag is meant to signify:
if your just making an LTS patch release and something in a Feature release
already has a ``release`` tag to indicate it being the latest release, you
don't have to alter the remote/origin repo's ``release`` tag at all.

  • Python projects may additionally have a make upload target to upload the release to PyPI.

  • (Starting from Zeek v4.0.0+) Ensure the zeek-docs repo has generated all the latest content:

    # Make sure to use have a fully up-to-date local Zeek build before building docs
$ ./configure && make -j $(nproc)
$ ./ci/update-zeekygen-docs.sh

# If there's changes, push those to the zeek-docs repo.
# If this is for a maintenance release, you'll likely be pushing
# a zeek-docs 'release/x.y' branch rather than 'master'.
$ ( cd doc && git add -u scripts/ && git commit -m 'Generate docs' && git push )

# Check the sphinx docs also build successfully
$ ( cd doc && make )

# Also update the submodule in 'zeek' if needed
$ git add -u doc && git commit -m 'Update doc submodule [nomail] [skip ci]' && git push

  • If there are pull requests to be merged from the zeek-security repo, first merge them into the appropriate branch (master/release) in that repo and then cherry-pick the merge commits from there into the main repo.

  • Finalize the Zeek repo

    • If you're creating an X.0.0 release (an initial LTS release), update all of the submodules to their current master branches. You can use the auxil/zeek-aux/devel-tools/git-move-submodules script to do this in an automated way. Be cautious as it will update all submodules to their master branches including ones that we don't control directly. It won't commit the changes right away but give you a list of commands to push the commits, so be sure to inspect the output before running them.

    • If you're creating an X.Y.0 release (an initial Feature or LTS release, but not a patch/bugfix release):

      • Create and push a release/X.Y branch off of master.

      • Switch back to master and create a commit that does the following:

        • Add a new section to NEWS for the next release.
        • Update VERSION to create a -dev placeholder for the start of the next version.
        • Update the testing/btest/scripts/site/local-compat.test to match the new version.

      • Add a tag to that commit to point to the -dev version. For exampled, after the 3.0.0 release, create a tag for 3.1.0-dev:

        $ git tag -a v3.1.0-dev -m "Start of 3.1.0 development"
$ git push --tags

      • The same procedure could technically also be done for patch releases, but it's not generally worth the trouble and additional tag-clutter: for patch releases, instead prefer to bump the version only during the final update-changes -R of that patch release.

      • For our Docker images, update the Github workflows to adapt the image tagging on the release branches. On the previous release branch, switch to using the lts tag (example). On the new release branch add the use of latest (example). On the previous LTS branch remove the additional image tag, so any additional releases on that branch only get tagged with its version number. The image build for the new release will trigger once you push its git tag.

    • Run update-changes -R vX.Y.Z (e.g. v3.0.0, v3.0.1, v3.1.0, or v3.1.1). If you're creating a Release Candidate, the tag is instead created/named like update-changes -B v3.0.0-rc1 (note the -B flag instead of -R, which also creates a beta tag instead of release -- these tags should be mostly traditional/historical at this point, but still created anyway. Some URLs out there may still use them to refer to "latest" release).

    • At this point, it's a good idea to run make dist, then do a quick sanity check of the resulting Zeek tarfile. E.g. from untar'd dir, check VERSION file contents, run the btest suite, etc. make dist will attempt to clean up any extra files in the clone you run it from, but check to make sure things such as macOS's .DS_Store files weren't included.

    • Run git push && git push --tags

  • Build tarfiles for all new releases: every repo comes with a make dist target to generate these.

  • Sign tarfiles: see the aux/zeek-aux/devel-tools/sign-file script as an example, but usually boils down to:

    $ for f in *.tar.gz; do gpg --detach-sign -a -u F8CB8019 --openpgp -o $f.asc $f; done

  • Push tarfiles and signatures to webserver: download.zeek.org is hosted on S3. simply push the files into the download.zeek.org bucket using either the web interface/console or CLI:

    $ aws s3 cp zeek-4.0.1.tar.gz s3://download.zeek.org/

    The index page is automatically regenerated using a lambda when objects change. This regeneration can take a few seconds. Please check that the new file does show up on https://download.zeek.org after a while. If you want to upload files that are not supposed to show up in the index, put them into the data/ subdirectory. Neither the directory nor the files in it are included in the directory index.

  • Update the downloads page at https://zeek.org/get-zeek/ via https://zeek.org/wp-admin/

    • Go to Pages -> Get Zeek -> Edit With Divi
    • Ensure correct release number/date and links to release tarfile/notes
    • For a few months of the year, there won't be any need for a Feature Release to to be listed (just the LTS Release), so add or remove a download box for a Feature Release as needed. e.g. it can say "Current Feature Release" and "Stable & supported until the next release" and otherwise follow the same structure as the LTS release.

  • Create a release tag in the zeek-docs repository (it's also a submodule of zeek in the doc/ dir). Commands to do that look may look like (replace with actual version numbers):

    $ git tag -a v3.0.1 -m "Docs for Zeek 3.0.1"
$ git push --tags

    Move the current and LTS tags, if necessary. The former points to whatever the latest patch release is, while the later points to whatever the latest patch release of the long-term supported version is.

    Now activate the new versions on Read the Docs: https://app.readthedocs.org/projects/zeek-docs/

    You can monitor the build succeeds here: https://app.readthedocs.org/projects/zeek-docs/builds/

    Once the builds complete, refresh https://docs.zeek.org and check the version indicators display as they're supposed to.

    When moving tags, you generally need to manually trigger a build on the Read the Docs web interface for it to correctly pick up the changes: "Edit" the version/tag, "wipe" it, and then trigger a build manually.

    Docs associated with specific version numbers can be activated/deactivated/hidden via the RTD web interface at this point.

    If a new Broker release was done at the same time, the builds on RTD must be done for Broker as well from https://readthedocs.org/projects/bro-broker/.

  • Create a new GitHub release at https://github.com/zeek/zeek/releases by filling in the release notes and uploading the .tar.gz and .tar.gz.asc files. Note that these file-uploads only help because GitHub’s automatic process for creating zip/tarfiles of release tags doesn't include submodules (and that tends to confuse users). Hopefully GitHub changes this in the future.

    For the release message, you can typically just paste the version-relevant release notes as copied from the NEWS file.

  • If there's a blog post to make, do that from https://zeek.org/wp-admin/

  • Make an announcement post on Discourse under the Announcement category, and tag it with the announcement tag. This will also automatically send a notification to the #general channel in the Zeek Slack server that the post has been made.

  • Update the Binary Packages

  • Update the OS matrix.

  • Update the Docker Hub README to show the full image version list.

  • Announce on other social media

  • Close the GitHub release milestone (unless still in RC-phase): https://github.com/zeek/zeek/milestones

  • Close the GitHub release project (unless still in RC-phase): https://github.com/orgs/zeek/projects?type=beta

  • Cleanup/organize the Upcoming Bug-Fix List: https://github.com/zeek/zeek/issues/724.

    • If there were any security issues in the release that weren't in that public list, can add them now.

Release Candidates

Releasing a beta version is roughly the same process as above for the real release, with the following tweaks:

  • update-changes has a separate option -B <version> to make a beta version. Using that creates a corresponding beta tag instead of release (the latter remains untouched). A beta version number must be of the form vX.Y.Z-rc* (e.g. v3.0.0-rc1).
  • When doing a Zeek beta, it’s usually best to simply go ahead and make releases of all the submodules first. Often the submodules won’t change anymore between beta and release, so that saves some time later. If a submodule changes, just do another patch-release for it. Once all submodules are tagged as releases, prepare the Zeek RC.
Clone this wiki locally