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.
45   * Even changes to `RELEASES.md` are pushed to `main` first.
464. On the 20th of every month (same CI job as before) another CI job will run
47   performing:
48   * Download the current `main` branch.
49   * Update the release date of `X.Y.Z` to today in `RELEASES.md`
50   * Open a PR against `main` for this change
51   * Reset to `release-X.Y.Z`
52   * Update the release date of `X.Y.Z` to today in `RELEASES.md`
53   * Add a special marker to the commit message to indicate a tag should be made.
54   * Open a PR against `release-X.Y.Z` for this change
55   * This step can also be [triggered manually][ci-trigger] with the `main`
56     branch and the `release-latest` argument.
575. **A maintainer of Wasmtime merges these two PRs**
58   * The PR against `main` is a small update to the release notes and should be
59     mergeable immediately.
60   * The PR against `release-X.Y.Z`, when merged, will trigger the next steps due
61     to the marker in the commit message. A maintainer should double-check there
62     are [no open security issues][rustsec-issues], but otherwise it's expected
63     that all other release issues are resolved by this point.
646. The `.github/workflow/push-tag.yml` workflow is triggered on all commits
65   including the one just created with a PR merge. This workflow will:
66   * Scan the git logs of pushed changes for the special marker added by
67     `release-process.yml`.
68   * If found, tags the current `main` commit and pushes that to the main
69     repository.
707. Once a tag is created CI runs in full on the tag itself. CI for tags will
71   create a GitHub release with release artifacts and it will also publish
72   crates to crates.io. This is orchestrated by `.github/workflows/main.yml`.
73
74If all goes well you won't have to read up much on this and after hitting the
75Big Green Button for the automatically created PRs everything will merrily
76carry on its way.
77
78[rustsec-issues]: https://github.com/bytecodealliance/wasmtime/issues?q=RUSTSEC+is%3Aissue+is%3Aopen+
79[ci-trigger]: https://github.com/bytecodealliance/wasmtime/actions/workflows/release-process.yml
80
81## Releasing a patch version
82
83Making a patch release is somewhat more manual than a major version, but like
84before there's automation to help guide the process as well and take care of
85more mundane bits.
86
87This is a list of steps taken to perform a patch release for 2.0.1 for example.
88Like above human interaction is indicated with **bold** text in these steps.
89
901. **Necessary changes are backported to the `release-2.0.0` branch from
91   `main`**
92   * All changes must land on `main` first (if applicable) and then get
93     backported to an older branch. Release branches should already exist from
94     the above major release steps.
95   * CI may not have been run in some time for release branches so it may be
96     necessary to backport CI fixes and updates from `main` as well.
97   * When merging backports maintainers need to double-check that the
98     `PUBLIC_CRATES` listed in `scripts/publish.rs` do not have
99     semver-API-breaking changes (in the strictest sense). All security fixes
100     must be done in such a way that the API doesn't break between the patch
101     version and the original version.
102   * Don't forget to write patch notes in `RELEASES.md` for backported changes.
1032. **The patch release process is [triggered manually][ci-trigger] with
104   the `release-2.0.0` branch and the `release-patch` argument**
105   * This will run the `release-process.yml` workflow. The `scripts/publish.rs`
106     script will be run with the `bump-patch` argument.
107   * The changes will be committed with a special marker indicating a release
108     needs to be made.
109   * A PR will be created from a temporary `ci/*` branch to the `release-2.0.0`
110     branch which, when merged, will trigger the release process.
1113. **Review the generated PR and merge it**
112   * This will resume from step 6 above in the major release process where the
113     special marker in the commit message generated by CI will trigger a tag to
114     get pushed which will further trigger the rest of the release process.
115   * Please make sure to update the `RELEASES.md` at this point to include the
116     `Released on` date by pushing directly to the branch associated with the
117     PR.
1184. **Forward-port the release notes to main**
119   * Once the release is done, please forward-port the release notes to the
120     `RELEASES.md` on the main branch, to ensure consistency in future releases.
121
122After a patch release has been made you'll also want to double-check that the
123release notes on the patch branch are in sync with the `main` branch.
124
125[bump-version]: https://github.com/bytecodealliance/wasmtime/actions/workflows/bump-version.yml
126
127## Releasing a security patch
128
129When making a patch release that has a security-related fix the contents of the
130patch are often kept private until the day of the patch release which means that
131the process here is slightly different from the patch release process above. In
132addition the precise [runbook is currently under discussion in an
133RFC](https://github.com/bytecodealliance/rfcs/pull/20) for security patches, so
134this intends to document what we've been doing so far and it'll get updated when
135the runbook is merged.
136
1371. **The fix for the security issue is developed in a GitHub Security
138   Advisory**
139   * This will not have any CI run, it's recommended to run `./ci/run-tests.sh`
140     locally at least.
141   * Develop fixes for all branches that will get a patch release in the
142     advisory, one PR per branch. When the advisory is published all branches
143     will be merged simultaneously. Be sure to run `./ci/run-tests.sh` in each
144     branch.
145   * Don't forget to update `RELEASES.md` with notes about the release on
146     each branch.
1472. **Send a PR for the version bump when an email goes out announcing there will
148   be a security release**
149   * An email is sent to the bytecodealliance security mailing list ahead of a
150     patch release to announce that a patch release will happen. At this time you
151     should [trigger the version bump][ci-trigger] against the appropriate
152     `release-x.y.z` branches with the `release-patch` argument.
153   * This will send a PR, but you should not merge it. Instead use this PR and
154     the time ahead of the security release to fix any issues with CI. Older
155     `release-x.y.z` branches haven't run CI in awhile so they may need to
156     backport fixes of one variety or another. DO NOT include the actual fix for
157     the security issue into the PR, that comes in the next step.
1583. **Make the advisories/patches public**
159   * Publishing the GitHub Security Advisory will merge all the PRs into each
160     branch from the advisory. Note that CI will run for release branches but
161     `main` will probably fail CI since it expected to be merged through the
162     merge queue, but that's ok.
163   * Double-check that CI for release branches finishes and completes
164     successfully.
1654. **Merge the version-bump PR**
166   * Like the patch release process this will kick everything else into motion.
167     Note that the actual security fixes should be merged either before or as
168     part of this PR.
169
170After a security release has been made you'll also want to double-check that
171the release notes on the branch are in sync with the `main` branch.
172