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
76Making a patch release is somewhat more manual than a major version, but like
77before there's automation to help guide the process as well and take care of
78more mundane bits.
79
80This is a list of steps taken to perform a patch release for 2.0.1 for example.
81Like above human interaction is indicated with **bold** text in these steps.
82
831. **Necessary changes are backported to the `release-2.0.0` branch from
84   `main`**
85   * All changes must land on `main` first (if applicable) and then get
86     backported to an older branch. Release branches should already exist from
87     the above major release steps.
88   * CI may not have been run in some time for release branches so it may be
89     necessary to backport CI fixes and updates from `main` as well.
90   * When merging backports maintainers need to double-check that the
91     `PUBLIC_CRATES` listed in `scripts/publish.rs` do not have
92     semver-API-breaking changes (in the strictest sense). All security fixes
93     must be done in such a way that the API doesn't break between the patch
94     version and the original version.
95   * Don't forget to write patch notes in `RELEASES.md` for backported changes.
962. **The patch release process is [triggered manually][ci-trigger] with
97   the `release-2.0.0` branch and the `release-patch` argument**
98   * This will run the `release-process.yml` workflow. The `scripts/publish.rs`
99     script will be run with the `bump-patch` argument.
100   * The changes will be committed with a special marker indicating a release
101     needs to be made.
102   * A PR will be created from a temporary `ci/*` branch to the `release-2.0.0`
103     branch which, when merged, will trigger the release process.
1043. **Review the generated PR and merge it**
105   * This will resume from step 6 above in the major release process where the
106     special marker in the commit message generated by CI will trigger a tag to
107     get pushed which will further trigger the rest of the release process.
108   * Please make sure to update the `RELEASES.md` at this point to include the
109     `Released on` date by pushing directly to the branch associated with the
110     PR.
111
112[bump-version]: https://github.com/bytecodealliance/wasmtime/actions/workflows/bump-version.yml
113
114## Releasing a security patch
115
116For security releases see the documentation [of the vulnerability
117runbook](./security-vulnerability-runbook.md).
118
119## Releasing Notes
120
121Release notes for Wasmtime are written in the `RELEASES.md` file in the root of
122the repository. Management of this file looks like:
123
124* (theoretically) All changes on `main` which need to write an entry in
125  `RELEASES.md`.
126* When the `main` branch gets a version the `RELEASES.md` file is emptied and
127  replaced with `ci/RELEASES-template.md`. An entry for the upcoming release is
128  added to the bulleted list at the bottom.
129* (realistically) After a `release-X.Y.Z` branch is created release notes are
130  updated and edited on the release branch.
131
132This means that `RELEASES.md` only has release notes for the release branch that
133it is on. Historical release notes can be found through links at the bottom to
134previous copies of `RELEASES.md`
135