Release Process
This is intended to serve as documentation for Wasmtime's release process. It's largely an internal checklist for those of us performing a Wasmtime release, but others might be curious in this as well!
Releasing a major version
Major versions of Wasmtime are released once-a-month. Most of this is automatic and all that needs to be done is to merge GitHub PRs that CI will generate. At a high-level the structure of Wasmtime's release process is:
- On the 5th of every month a new
release-X.Y.Zbranch is created with the current contents ofmain. - On the 20th of every month this release branch is published to crates.io and release artifacts are built.
This means that Wasmtime releases are always at least two weeks behind
development on main and additionally happen once a month. The lag time behind
main is intended to give time to fuzz changes on main as well as allow
testing for any users using main. It's expected, though, that most consumers
will likely use the release branches of wasmtime.
A detailed list of all the steps in the release automation process are below. The steps requiring interactions are bolded, otherwise everything else is automatic and this is documenting what automation does.
- On the 5th of every month, (configured via
.github/workflows/release-process.yml) a CI job will run and do these steps:- Download the current
mainbranch - Push the
mainbranch torelease-X.Y.Z - Run
./scripts/publish.rswith thebumpargument - Commit the changes
- Push these changes to a temporary
ci/*branch - Open a PR with this branch against
main - This step can also be triggered manually with the
mainbranch and thecutargument.
- Download the current
- A maintainer of Wasmtime merges this PR
- It's intended that this PR can be immediately merged as the release branch has been created and all it's doing is bumping the version.
- Time passes and the
release-X.Y.Zbranch is maintained- All changes land on
mainfirst, then are backported torelease-X.Y.Zas necessary.
- All changes land on
- On the 20th of every month (same CI job as before) another CI job will run
performing:
- Reset to
release-X.Y.Z - Update the release date of
X.Y.Zto today inRELEASES.md - Add a special marker to the commit message to indicate a tag should be made.
- Open a PR against
release-X.Y.Zfor this change - This step can also be triggered manually with the
mainbranch and therelease-latestargument.
- Reset to
- A maintainer of Wasmtime merges this PR
- When merged, will trigger the next steps due to the marker in the commit message. A maintainer should double-check there are no open security issues, but otherwise it's expected that all other release issues are resolved by this point.
- The main CI workflow at
.github/workflow/main.ymlhas special logic at the end such that pushes to therelease-*branch will scan the git logs of pushed changes for the special marker added byrelease-process.yml. If found and CI passes a tag is created and pushed. - Once a tag is created the
.github/workflows/publish-*workflows run. One publishes all crates as-is to crates.io and the other will download all artifacts from themain.ymlworkflow and then upload them all as an official release.
If all goes well you won't have to read up much on this and after hitting the Big Green Button for the automatically created PRs everything will merrily carry on its way.
Releasing a patch version
Wasmtime does not currently have a cadence for patch version nor a strict set of criteria. It's done on an as-needed basis. Two requirements, however are:
-
All changes must land on
mainfirst (if applicable) and then get backported to an older branch. Release branches should already exist from the above major release steps. -
When a patch release is made it must be applied to all supported versions that need the patch. Wasmtime will not release a patch release until all versions have been equally patched to ensure that releases remain consistent.
Making a patch release is somewhat more manual than a major version, but like before there's automation to help guide the process as well and take care of more mundane bits.
This is a list of steps taken to perform a patch release for 2.0.1 for example. Like above human interaction is indicated with bold text in these steps.
- Necessary changes are backported to the
release-2.0.0branch frommain- CI may not have been run in some time for release branches so it may be
necessary to backport CI fixes and updates from
mainas well. - When merging backports maintainers need to double-check that the
PUBLIC_CRATESlisted inscripts/publish.rsdo not have semver-API-breaking changes (in the strictest sense). All security fixes must be done in such a way that the API doesn't break between the patch version and the original version. - Don't forget to write patch notes in
RELEASES.mdfor backported changes.
- CI may not have been run in some time for release branches so it may be
necessary to backport CI fixes and updates from
- The patch release process is triggered manually with
the
release-2.0.0branch and therelease-patchargument- This will run the
release-process.ymlworkflow. Thescripts/publish.rsscript will be run with thebump-patchargument. - The changes will be committed with a special marker indicating a release needs to be made.
- A PR will be created from a temporary
ci/*branch to therelease-2.0.0branch which, when merged, will trigger the release process.
- This will run the
- Review the generated PR and merge it
- This will resume from step 6 above in the major release process where the special marker in the commit message generated by CI will trigger a tag to get pushed which will further trigger the rest of the release process.
- Please make sure to update the
RELEASES.mdat this point to include theReleased ondate by pushing directly to the branch associated with the PR.
Releasing a security patch
For security releases see the documentation of the vulnerability runbook.
Releasing Notes
Release notes for Wasmtime are written in the RELEASES.md file in the root of
the repository. Management of this file looks like:
- (theoretically) All changes on
mainwhich need to write an entry inRELEASES.md. - When the
mainbranch gets a version theRELEASES.mdfile is emptied and replaced withci/RELEASES-template.md. An entry for the upcoming release is added to the bulleted list at the bottom. - (realistically) After a
release-X.Y.Zbranch is created release notes are updated and edited on the release branch.
This means that RELEASES.md only has release notes for the release branch that
it is on. Historical release notes can be found through links at the bottom to
previous copies of RELEASES.md
Keeping Old release branch CI up-to-date
Over time CI configuration goes out of date and may need to be updated. The Wasmtime repository has a cron job via GitHub Actions to run release CI on all supported release branches on a weekly basis to try to weed out these problems. If a release branch CI fails it'll open an issue and maintainers should resolve it expediently.
Where possible old release branch CI should not update software to fix CI. Try to pin to older versions if something wasn't pinned already for example. Sometimes though updates are inevitable and may be required.