1# Release Process 2 3This is intended to serve as documentation for Wasmtime's release process. It's 4largely an internal checklist for those of us performing a Wasmtime release, but 5others might be curious in this as well! 6 7## Releasing a major version 8 9Major versions of Wasmtime are released once-a-month. Most of this is automatic 10and all that needs to be done is to merge GitHub PRs that CI will 11generate. At a high-level the structure of Wasmtime's release process is: 12 13* On the 5th of every month a new `release-X.Y.Z` branch is created with the 14 current contents of `main`. 15* On the 20th of every month this release branch is published to crates.io and 16 release artifacts are built. 17 18This means that Wasmtime releases are always at least two weeks behind 19development on `main` and additionally happen once a month. The lag time behind 20`main` is intended to give time to fuzz changes on `main` as well as allow 21testing for any users using `main`. It's expected, though, that most consumers 22will likely use the release branches of wasmtime. 23 24A detailed list of all the steps in the release automation process are below. 25The steps requiring interactions are **bolded**, otherwise everything else is 26automatic and this is documenting what automation does. 27 281. On the 5th of every month, (configured via 29 `.github/workflows/release-process.yml`) a CI job 30 will run and do these steps: 31 * Download the current `main` branch 32 * Push the `main` branch to `release-X.Y.Z` 33 * Run `./scripts/publish.rs` with the `bump` argument 34 * Commit the changes 35 * Push these changes to a temporary `ci/*` branch 36 * Open a PR with this branch against `main` 37 * This step can also be [triggered manually][ci-trigger] with the `main` 38 branch and the `cut` argument. 392. **A maintainer of Wasmtime merges this PR** 40 * It's intended that this PR can be immediately merged as the release branch 41 has been created and all it's doing is bumping the version. 423. **Time passes and the `release-X.Y.Z` branch is maintained** 43 * All changes land on `main` first, then are backported to `release-X.Y.Z` as 44 necessary. 454. On the 20th of every month (same CI job as before) another CI job will run 46 performing: 47 * Reset to `release-X.Y.Z` 48 * Update the release date of `X.Y.Z` to today in `RELEASES.md` 49 * Add a special marker to the commit message to indicate a tag should be made. 50 * Open a PR against `release-X.Y.Z` for this change 51 * This step can also be [triggered manually][ci-trigger] with the `main` 52 branch and the `release-latest` argument. 535. **A maintainer of Wasmtime merges this PR** 54 * When merged, will trigger the next steps due 55 to the marker in the commit message. A maintainer should double-check there 56 are [no open security issues][rustsec-issues], but otherwise it's expected 57 that all other release issues are resolved by this point. 586. The main CI workflow at `.github/workflow/main.yml` has special logic 59 at the end such that pushes to the `release-*` branch will scan the git logs 60 of pushed changes for the special marker added by `release-process.yml`. If 61 found and CI passes a tag is created and pushed. 627. Once a tag is created the `.github/workflows/publish-*` workflows run. One 63 publishes all crates as-is to crates.io and the other will download all 64 artifacts from the `main.yml` workflow and then upload them all as an 65 [official release](https://github.com/bytecodealliance/wasmtime/releases). 66 67If all goes well you won't have to read up much on this and after hitting the 68Big Green Button for the automatically created PRs everything will merrily 69carry on its way. 70 71[rustsec-issues]: https://github.com/bytecodealliance/wasmtime/issues?q=RUSTSEC+is%3Aissue+is%3Aopen+ 72[ci-trigger]: https://github.com/bytecodealliance/wasmtime/actions/workflows/release-process.yml 73 74## Releasing a patch version 75 76Wasmtime does not currently have a cadence for patch version nor a strict set 77of criteria. It's done on an as-needed basis. Requirements, however, are: 78 79* All changes must land on `main` first (if applicable) and then get backported 80 to an older branch. Release branches should already exist from the above 81 major release steps. 82 83* When a patch release is made it must be applied to [all supported 84 versions](./stability-release.md#current-versions) that need the patch. 85 Wasmtime will not release a patch release until all versions have been 86 equally patched to ensure that releases remain consistent. 87 88* Patch releases must not contain API-breaking changes in public crates. The 89 list of `PUBLIC_CRATES` in `scripts/publish.rs` is the list of crates to worry 90 about in terms of breaking changes. 91 92* Wasm-level ABI-breaking changes are by default not allowed in patch releases. 93 Users are expected to, for example, be able to load `*.cwasm` artifacts from 94 before the patch release is made. If an ABI-breaking change is necessary then 95 be sure to update `crates/wasmtime/src/engine/serialization.rs` and the 96 `WasmtimeVersion` matching strategy to modify the string to ensure older 97 artifacts cannot be loaded. 98 99Making a patch release is somewhat more manual than a major version, but like 100before there's automation to help guide the process as well and take care of 101more mundane bits. 102 103This is a list of steps taken to perform a patch release for 2.0.1 for example. 104Like above human interaction is indicated with **bold** text in these steps. 105 1061. **Necessary changes are backported to the `release-2.0.0` branch from 107 `main`** 108 * CI for supported branches is run weekly, even after release, to ensure that 109 it's at most broken for a week. Nevertheless issues come up, so be aware 110 that CI may be green on `main` but red on a release branch. 111 * When merging backports maintainers need to double-check that the 112 `PUBLIC_CRATES` listed in `scripts/publish.rs` do not have 113 semver-API-breaking changes (in the strictest sense). All security fixes 114 must be done in such a way that the API doesn't break between the patch 115 version and the original version. 116 * Don't forget to write patch notes in `RELEASES.md` for backported changes. 1172. **The patch release process is [triggered manually][ci-trigger] with 118 the `release-2.0.0` branch and the `release-patch` argument** 119 * This will run the `release-process.yml` workflow. The `scripts/publish.rs` 120 script will be run with the `bump-patch` argument. 121 * The changes will be committed with a special marker indicating a release 122 needs to be made. 123 * A PR will be created from a temporary `ci/*` branch to the `release-2.0.0` 124 branch which, when merged, will trigger the release process. 1253. **Review the generated PR and merge it** 126 * This will resume from step 6 above in the major release process where the 127 special marker in the commit message generated by CI will trigger a tag to 128 get pushed which will further trigger the rest of the release process. 129 * Please make sure to update the `RELEASES.md` at this point to include the 130 `Released on` date by pushing directly to the branch associated with the 131 PR. 132 133[bump-version]: https://github.com/bytecodealliance/wasmtime/actions/workflows/bump-version.yml 134 135## Releasing a security patch 136 137For security releases see the documentation [of the vulnerability 138runbook](./security-vulnerability-runbook.md). 139 140## Releasing Notes 141 142Release notes for Wasmtime are written in the `RELEASES.md` file in the root of 143the repository. Management of this file looks like: 144 145* (theoretically) All changes on `main` bundle an appropriate update of 146 `RELEASES.md`. In practice this almost never happens. 147* When the `main` branch gets a version bump the `RELEASES.md` file is emptied 148 and replaced with `ci/RELEASES-template.md`. An entry for the upcoming release 149 is added to the bulleted list at the bottom. 150* (realistically) After a `release-X.Y.Z` branch is created release notes are 151 updated and edited on the release branch directly. 152 153This means that `RELEASES.md` only has release notes for the release branch that 154it is on. Historical release notes can be found through links at the bottom to 155previous copies of `RELEASES.md` 156 157## Keeping Old release branch CI up-to-date 158 159Over time CI configuration goes out of date and may need to be updated. The 160Wasmtime repository has a cron job via GitHub Actions to run release CI on all 161supported release branches on a weekly basis to try to weed out these problems. 162If a release branch CI fails it'll open an issue and maintainers should resolve 163it expediently. 164 165Where possible old release branch CI should not update software to fix CI. Try 166to pin to older versions if something wasn't pinned already for example. 167Sometimes though updates are inevitable and may be required. 168