T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fixup release documentation (#3988)

Browse Source 
* Fill out some missing comments on the workflow itself
* Fix some formatting in the book to properly render sub-bullets
This commit is contained in:
Alex Crichton
2022-04-05 14:14:44 -05:00
committed by GitHub
parent 011d2e1faa
commit 35377bd33f
2 changed files with 87 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
.github/workflows/release-process.yml vendored
View File

@@ -1,12 +1,18 @@
# The purpose of this workflow is to, once a month, trigger Wasmtime's release # The purpose of this workflow is to orchestrate Wasmtime's release process as
# process. All that actually happens here is that whenever this is triggered it # much as possible. This specific workflow is responsible for a few timed parts
# will send a PR to the main repository with the version numbers automatically # of the process:
# bumped. The next stage of the process is to simply merge the PR, and the
# `push-tag.yml` process takes over from there.
# #
# Note that this creates a commit and a PR with a personal access token to # * On the 5th of every month a new release branch is automatically created and
# ensure that the PR gets CI triggered on it. Additionally the commit message # the version number of the `main` branch is increased
# is specifically worded to get recognized by `push-tag.yml`. # * On the 20th of every month the previous release branch is published.
#
# This automation is all done through PRs except for the creation of the release
# branch itself which is an write-action performed by this script. Otherwise
# humans are ideally reviewing and rubber-stamping the output of the script all
# other steps of the way.
#
# Note that this script also helps manage patch releases by sending a PR to the
# release branch with a bumped version number for all crates with a patch-bump.
name: "Automated Release Process" name: "Automated Release Process"
on: on:
@@ -18,8 +24,7 @@ on:
- cron: '0 0 20 * *' - cron: '0 0 20 * *'
# Allow manually triggering this request via the button at # Allow manually triggering this request via the button at
# https://github.com/bytecodealliance/wasmtime/actions/workflows/bump-version.yml # https://github.com/bytecodealliance/wasmtime/actions/workflows/release-process.yml
# TODO
workflow_dispatch: workflow_dispatch:
inputs: inputs:
action: action:

144
docs/contributing-release-process.md
View File

@@ -15,7 +15,7 @@ generate. At a high-level the structure of Wasmtime's release process is:
* On the 20th of every month this release branch is published to crates.io and * On the 20th of every month this release branch is published to crates.io and
release artifacts are built. release artifacts are built.
This means that Wasmtime release are always at least two weeks behind 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 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 `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 testing for any users using `main`. It's expected, though, that most consumers
@@ -28,39 +28,39 @@ automatic and this is documenting what automation does.
1. On the 5th of every month, (configured via 1. On the 5th of every month, (configured via
`.github/workflows/release-process.yml`) a CI job `.github/workflows/release-process.yml`) a CI job
will run and do these steps: will run and do these steps:
* Download the current `main` branch * Download the current `main` branch
* Push the `main` branch to `release-X.Y.Z` * Push the `main` branch to `release-X.Y.Z`
* Run `./scripts/publish.rs` with the `bump` argument * Run `./scripts/publish.rs` with the `bump` argument
* Commit the changes * Commit the changes
* Push these changes to a temporary `ci/*` branch * Push these changes to a temporary `ci/*` branch
* Open a PR with this branch against `main` * Open a PR with this branch against `main`
* This step can also be [triggered manually][ci-trigger] with the `main` * This step can also be [triggered manually][ci-trigger] with the `main`
branch and the `cut` argument. branch and the `cut` argument.
2. **A maintainer of Wasmtime merges this PR** 2. **A maintainer of Wasmtime merges this PR**
* It's intended that this PR can be immediately merged as the release branch * 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. has been created and all it's doing is bumping the version.
3. **Time passes and the `release-X.Y.Z` branch is maintained** 3. **Time passes and the `release-X.Y.Z` branch is maintained**
* All changes land on `main` first, then are backported to `release-X.Y.Z` as * All changes land on `main` first, then are backported to `release-X.Y.Z` as
necessary. necessary.
* Even changes to `RELEASES.md` are pushed to `main` first. * Even changes to `RELEASES.md` are pushed to `main` first.
4. On the 20th of every month (same CI job as before) another CI job will run 4. On the 20th of every month (same CI job as before) another CI job will run
performing: performing:
* Download the current `main` branch. * Download the current `main` branch.
* Update the release date of `X.Y.Z` to today in `RELEASES.md` * Update the release date of `X.Y.Z` to today in `RELEASES.md`
* Open a PR against `main` for this change * Open a PR against `main` for this change
* Reset to `release-X.Y.Z` * Reset to `release-X.Y.Z`
* Update the release date of `X.Y.Z` to today in `RELEASES.md` * Update the release date of `X.Y.Z` to today in `RELEASES.md`
* Add a special marker to the commit message to indicate a tag should be made. * Add a special marker to the commit message to indicate a tag should be made.
* Open a PR against `release-X.Y.Z` for this change * Open a PR against `release-X.Y.Z` for this change
* This step can also be [triggered manually][ci-trigger] with the `main` * This step can also be [triggered manually][ci-trigger] with the `main`
branch and the `release-latest` argument. branch and the `release-latest` argument.
5. **A maintainer of Wasmtime merges these two PRs** 5. **A maintainer of Wasmtime merges these two PRs**
* The PR against `main` is a small update to the release notes and should be * The PR against `main` is a small update to the release notes and should be
mergeable immediately. mergeable immediately.
* The PR against `release-X.Y.Z`, when merged, will trigger the next steps due * The PR against `release-X.Y.Z`, when merged, will trigger the next steps due
to the marker in the commit message. A maintainer should double-check there to the marker in the commit message. A maintainer should double-check there
are [no open security issues][rustsec-issues], but otherwise it's expected are [no open security issues][rustsec-issues], but otherwise it's expected
that all other release issues are resolved by this point. that all other release issues are resolved by this point.
6. The `.github/workflow/push-tag.yml` workflow is triggered on all commits 6. The `.github/workflow/push-tag.yml` workflow is triggered on all commits
including the one just created with a PR merge. This workflow will: including the one just created with a PR merge. This workflow will:
* Scan the git logs of pushed changes for the special marker added by * Scan the git logs of pushed changes for the special marker added by
@@ -89,29 +89,29 @@ Like above human interaction is indicated with **bold** text in these steps.
1. **Necessary changes are backported to the `release-2.0.0` branch from 1. **Necessary changes are backported to the `release-2.0.0` branch from
`main`** `main`**
* All changes must land on `main` first (if applicable) and then get * All changes must land on `main` first (if applicable) and then get
backported to an older branch. Release branches should already exist from backported to an older branch. Release branches should already exist from
the above major release steps. the above major release steps.
* CI may not have been run in some time for release branches so it may be * CI may not have been run in some time for release branches so it may be
necessary to backport CI fixes and updates from `main` as well. necessary to backport CI fixes and updates from `main` as well.
* When merging backports maintainers need to double-check that the * When merging backports maintainers need to double-check that the
`PUBLIC_CRATES` listed in `scripts/publish.rs` do not have `PUBLIC_CRATES` listed in `scripts/publish.rs` do not have
semver-API-breaking changes (in the strictest sense). All security fixes 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 must be done in such a way that the API doesn't break between the patch
version and the original version. version and the original version.
* Don't forget to write patch notes in `RELEASES.md` for backported changes. * Don't forget to write patch notes in `RELEASES.md` for backported changes.
2. **The patch release process is [triggered manually][ci-trigger] with 2. **The patch release process is [triggered manually][ci-trigger] with
the `release-2.0.0` branch and the `release-patch` argument** the `release-2.0.0` branch and the `release-patch` argument**
* This will run the `release-process.yml` workflow. The `scripts/publish.rs` * This will run the `release-process.yml` workflow. The `scripts/publish.rs`
script will be run with the `bump-patch` argument. script will be run with the `bump-patch` argument.
* The changes will be committed with a special marker indicating a release * The changes will be committed with a special marker indicating a release
needs to be made. needs to be made.
* A PR will be created from a temporary `ci/*` branch to the `release-2.0.0` * A PR will be created from a temporary `ci/*` branch to the `release-2.0.0`
branch which, when merged, will trigger the release process. branch which, when merged, will trigger the release process.
3. **Review the generated PR and merge it** 3. **Review the generated PR and merge it**
* This will resume from step 6 above in the major release process where the * 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 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. get pushed which will further trigger the rest of the release process.
After a patch release has been made you'll also want to double-check that the After a patch release has been made you'll also want to double-check that the
release notes on the patch branch are in sync with the `main` branch. release notes on the patch branch are in sync with the `main` branch.
@@ -130,33 +130,33 @@ the runbook is merged.
1. **The fix for the security issue is developed in a GitHub Security 1. **The fix for the security issue is developed in a GitHub Security
Advisory** Advisory**
* This will not have any CI run, it's recommended to run `./ci/run-tests.sh` * This will not have any CI run, it's recommended to run `./ci/run-tests.sh`
locally at least. locally at least.
* This will also only be the patch for the `main` branch. You'll need to * This will also only be the patch for the `main` branch. You'll need to
locally maintain and develop patches for any older releases being backported locally maintain and develop patches for any older releases being backported
to. Note that from the major release process there should already be a to. Note that from the major release process there should already be a
branch for all older releases. branch for all older releases.
2. **Send a PR for the version bump when an email goes out announcing there will 2. **Send a PR for the version bump when an email goes out announcing there will
be a security release** be a security release**
* An email is sent to the bytecodealliance security mailing list ahead of a * An email is sent to the bytecodealliance security mailing list ahead of a
patch release to announce that a patch release will happen. At this time you patch release to announce that a patch release will happen. At this time you
should [trigger the version bump][ci-trigger] against the appropriate should [trigger the version bump][ci-trigger] against the appropriate
`release-x.y.z` branch with the `release-patch` argument. `release-x.y.z` branch with the `release-patch` argument.
* This will send a PR, but you should not merge it. Instead use this PR and * This will send a PR, but you should not merge it. Instead use this PR and
the time ahead of the security release to fix any issues with CI. Older the time ahead of the security release to fix any issues with CI. Older
`release-x.y.z` branches haven't run CI in awhile so they may need to `release-x.y.z` branches haven't run CI in awhile so they may need to
backport fixes of one variety or another. DO NOT include the actual fix for backport fixes of one variety or another. DO NOT include the actual fix for
the security issue into the PR, that comes in the next step. the security issue into the PR, that comes in the next step.
3. **Make the patches public** 3. **Make the patches public**
* For the `main` branch this will involve simply publishing the GitHub * For the `main` branch this will involve simply publishing the GitHub
Security Advisory. Note that CI will run after the advisory's changes are Security Advisory. Note that CI will run after the advisory's changes are
merged in on `main`. merged in on `main`.
* For the backported release branches you should either create a PR targeting * For the backported release branches you should either create a PR targeting
these branches or push the changes to the previous version-bump PRs. these branches or push the changes to the previous version-bump PRs.
3. **Merge the version-bump PR** 3. **Merge the version-bump PR**
* Like the patch release process this will kick everything else into motion. * Like the patch release process this will kick everything else into motion.
Note that the actual security fixes should be merged either before or as Note that the actual security fixes should be merged either before or as
part of this PR. part of this PR.
After a security release has been made you'll also want to double-check that After a security release has been made you'll also want to double-check that
the release notes on the branch are in sync with the `main` branch. the release notes on the branch are in sync with the `main` branch.