Clone this wiki locally
See Release Cadence for the intended release schedule as well as explanation and visual representation of the versioning scheme.
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.Ybranch 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.
NEWSwith 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.zeekhas changed, point out how to adapt a previous one accordingly.
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
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)
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
If doing a Release Candidate for Zeek, you can skip this step since submodules may change during the release candidate testing cycle. Once Submodule releases can be completed once the testing cycle is done and the final Zeek release is being built.
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.
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 uploadtarget to upload the release to PyPI.
(Starting from Zeek v4.0.0+) Ensure the
zeek-docsrepo 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
Finalize the Zeek repo
If you're creating an X.Y.0 release (an initial Feature or LTS release, but not a patch/bugfix release):
release/X.Ybranch off of
Create a supplementary
update-changesknows to use a pre-release versioning scheme for all subsequent commits to
master. For example, after the 3.0.0 release, make/push a simple commit that reserves a spot in
NEWSfor future 3.1.0 Feature release changes, update
3.1.0-dev, and then tag that commit like:
$ git tag -a v3.1.0-dev -m "Start of 3.1.0 development" $ git push --tags
Also update the
testing/btest/scripts/site/local-compat.testfile to match the new version number so the test continues to pass.
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 -Rof 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
ltstag (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.
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
-Bflag instead of
-R, which also creates a
betatag 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
VERSIONfile contents, run the btest suite, etc.
make distwill 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_Storefiles weren't included.
git push && git push --tags
Build tarfiles for all new releases: every repo comes with a
make disttarget to generate these.
Sign tarfiles: see the
aux/zeek-aux/devel-tools/sign-filescript 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.
- 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-docsrepository (it's also a submodule of
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
LTStags, 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://readthedocs.org/projects/zeek-docs/versions/
You can monitor the build succeeds here: https://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.ascfiles. 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
- Some other notable sub-projects may also upload release files to GitHub. For example, Broker does, too: https://github.com/zeek/broker/releases
If there's a blog post to make, do that from https://zeek.org/wp-admin/
Send an announcement email to email@example.com and firstname.lastname@example.org. Optionally sign the mail if you think it important (usually isn't because the announcement only contains links to HTTPS-hosted release notes along with signed-tarfile):
$ gpg --clear-sign -a -u F8CB8019 --openpgp -o <output name>.asc.txt <input file>
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/zeek/zeek/projects
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.
Releasing a beta version is roughly the same process as above for the real release, with the following tweaks:
update-changeshas a separate option
-B <version>to make a beta version. Using that creates a corresponding
betatag instead of
release(the latter remains untouched). A beta version number must be of the form
- 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.