Browse Source

Refactor how release notes are managed (#8680)

* Refactor how release notes are managed

This commit updates how Wasmtime manages release notes across released
versions of Wasmtime. One of the most onerous parts about releases right
now is writing release notes in all the locations and making sure
they're all up-to-date and in-sync. This is inevitably forgotten in some
cases and various pieces will slip through the cracks. The basic idea of
this PR is to change our release notes to only document the release
branch that they're on. All historical release notes are relegated to
historical branches.

With this change there's no longer any need to backport or forward-port
release notes for any changes. Instead release notes are written once
on one branch and that's it.

The major downside of this change is that there's no easy way to get a
bird's eye view of all release notes for Wasmtime any more. If necessary
that could theoretically be automated in the future (like
https://releases.rs/), but for now this feels like an acceptable
compromise to make releases much easier.

The contents of this PR are to update `RELEASES.md` with back-links to
historical release notes as well as the various pieces of automation we
have about managing release notes.

* Add more notes about the release process

* Fix a typo

* Make it more obvious that patch releases are documented
pull/8689/head
Alex Crichton 6 months ago
committed by GitHub
parent
commit
14226457ae
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
  1. 52
      .github/workflows/release-process.yml
  2. 4093
      RELEASES.md
  3. 3
      ci/RELEASES-template.md
  4. 18
      ci/update-release-date.rs
  5. 51
      docs/contributing-release-process.md

52
.github/workflows/release-process.yml

@ -63,7 +63,16 @@ jobs:
./publish bump
num=$(./ci/print-current-version.sh)
# Add a new section to the release notes for the new version.
# Remove all release notes for the current version now that the
# release branch has been created. Additionally add an entry in the
# list of all versions pointing to the release notes on the newly
# created branch.
sed -i '0,/-----------/d' RELEASES.md
version_with_trailing_x=$(echo $cur | sed 's/.$/x/')
sed -i "/ARCHIVE_START/a * [$version_with_trailing_x](https://github.com/${{ github.repository }}/blob/release-$cur/RELEASES.md)" RELEASES.md
# Use `RELEASES-template.md` as the new release notes and then append
# the archive of all historical releases to the end of it.
cp RELEASES.md backup-releases
sed "s/VERSION/$num/" ci/RELEASES-template.md > RELEASES.md
cat backup-releases >> RELEASES.md
@ -84,15 +93,13 @@ jobs:
cat > pr-body <<-EOF
This is an [automated pull request][process] from CI which indicates that the next [\`release-$cur\` branch][branch] has been created and the \`main\` branch is getting its version number bumped from $cur to $num.
Maintainers should take a moment to review the [release notes][RELEASES.md] for $cur, and if any changes are necessary send PRs to the \`main\` branch to update [RELEASES.md] and then backport these PRs to the [release branch][branch].
Maintainers should also review that aarch64-apple-darwin builds are passing via [embark's CI](https://buildkite.com/embark-studios/wasmtime-aarch64-apple-darwin).
Maintainers should take a moment to review the [release notes][RELEASES.md] for $cur and any updates should be made directly to the [release branch][branch].
Another automated PR will be made in roughly 2 weeks time when for the actual release itself.
If any issues arise on the \`main\` branch before the release is made then the issue should first be fixed on \`main\` and then backport to the \`release-$cur\` branch.
[RELEASES.md]: https://github.com/${{ github.repository }}/blob/main/RELEASES.md
[RELEASES.md]: https://github.com/${{ github.repository }}/blob/release-$cur/RELEASES.md
[branch]: https://github.com/${{ github.repository }}/tree/release-$cur
[process]: https://docs.wasmtime.dev/contributing-release-process.html
EOF
@ -109,37 +116,6 @@ jobs:
rustc ci/find-latest-release.rs -o /tmp/find-latest-release
cur=`/tmp/find-latest-release`
# Update the release date of $cur in RELEASES.md
rustc ci/update-release-date.rs -o /tmp/update-release-date
/tmp/update-release-date $(date +'%Y-%m-%d')
git commit --allow-empty -a -F-<<EOF
Update release date of Wasmtime $cur
EOF
git push origin HEAD:ci/release-date-for-$cur
# In addition to the PR we'll make below to perform the actual release
# make a second PR to the `main` branch to note the release date in
# the release notes.
cat > pr-body <<-EOF
This is an [automated pull request][process] from CI which is updating the release date of Wasmtime $cur to today. This PR's base branch is \`main\` and a second PR will be coming to perform the actual release which will be targeted at \`release-$cur\`.
[process]: https://docs.wasmtime.dev/contributing-release-process.html
EOF
body=$(jq -sR < ./pr-body)
curl --include --request POST \
https://api.github.com/repos/${{ github.repository }}/pulls \
--header "Authorization: token ${{ secrets.PERSONAL_ACCESS_TOKEN }}" \
--data @- << EOF
{
"head": "ci/release-date-for-$cur",
"base": "main",
"title": "Update release date of Wasmtime $cur",
"body": $body,
"maintainer_can_modify": true
}
EOF
# Move to the most recent release branch, update the release date and
# commit it, indicating that the commit is what will get tagged and
# released
@ -163,7 +139,7 @@ jobs:
It's recommended that maintainers double-check that [RELEASES.md] is up-to-date and that there are no known issues before merging this PR. When this PR is merged a release tag will automatically created, crates will be published, and CI artifacts will be produced.
[RELEASES.md]: https://github.com/${{ github.repository }}/blob/main/RELEASES.md
[RELEASES.md]: https://github.com/${{ github.repository }}/blob/release-$cur/RELEASES.md
[process]: https://docs.wasmtime.dev/contributing-release-process.html
[branch]: https://github.com/${{ github.repository }}/tree/release-$cur
EOF
@ -199,7 +175,7 @@ jobs:
It's recommended that maintainers double-check that [RELEASES.md] is up-to-date and that there are no known issues before merging this PR. When this PR is merged a release tag will automatically be created, crates will be published, and CI artifacts will be produced.
[RELEASES.md]: https://github.com/${{ github.repository }}/blob/main/RELEASES.md
[RELEASES.md]: https://github.com/${{ github.repository }}/blob/release-$num/RELEASES.md
[process]: https://docs.wasmtime.dev/contributing-release-process.html
EOF

4093
RELEASES.md

File diff suppressed because it is too large

3
ci/RELEASES-template.md

@ -1,5 +1,3 @@
--------------------------------------------------------------------------------
## VERSION
Unreleased.
@ -8,3 +6,4 @@ Unreleased.
### Changed
--------------------------------------------------------------------------------

18
ci/update-release-date.rs

@ -1,18 +0,0 @@
fn main() {
let date = std::env::args().nth(1).unwrap();
let relnotes = std::fs::read_to_string("RELEASES.md").unwrap();
let mut new_relnotes = String::new();
let mut counter = 0;
for line in relnotes.lines() {
if line.starts_with("Unreleased") {
counter += 1;
if counter == 2 {
new_relnotes.push_str(&format!("Released {}\n", date));
continue;
}
}
new_relnotes.push_str(line);
new_relnotes.push_str("\n");
}
std::fs::write("RELEASES.md", new_relnotes).unwrap();
}

51
docs/contributing-release-process.md

@ -42,34 +42,27 @@ automatic and this is documenting what automation does.
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
necessary.
* 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
performing:
* Download the current `main` branch.
* Update the release date of `X.Y.Z` to today in `RELEASES.md`
* Open a PR against `main` for this change
* Reset to `release-X.Y.Z`
* 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.
* Open a PR against `release-X.Y.Z` for this change
* This step can also be [triggered manually][ci-trigger] with the `main`
branch and the `release-latest` argument.
5. **A maintainer of Wasmtime merges these two PRs**
* The PR against `main` is a small update to the release notes and should be
mergeable immediately.
* The PR against `release-X.Y.Z`, when merged, will trigger the next steps due
5. **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][rustsec-issues], but otherwise it's expected
that all other release issues are resolved by this point.
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:
* Scan the git logs of pushed changes for the special marker added by
`release-process.yml`.
* If found, tags the current `main` commit and pushes that to the main
repository.
7. Once a tag is created CI runs in full on the tag itself. CI for tags will
create a GitHub release with release artifacts and it will also publish
crates to crates.io. This is orchestrated by `.github/workflows/main.yml`.
6. The main CI workflow at `.github/workflow/main.yml` has special logic
at the end such that pushes to the `release-*` branch will scan the git logs
of pushed changes for the special marker added by `release-process.yml`. If
found and CI passes a tag is created and pushed.
7. 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 the `main.yml` workflow and then upload them all as an
[official release](https://github.com/bytecodealliance/wasmtime/releases).
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
@ -115,12 +108,6 @@ Like above human interaction is indicated with **bold** text in these steps.
* Please make sure to update the `RELEASES.md` at this point to include the
`Released on` date by pushing directly to the branch associated with the
PR.
4. **Forward-port the release notes to main**
* Once the release is done, please forward-port the release notes to the
`RELEASES.md` on the main branch, to ensure consistency in future releases.
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.
[bump-version]: https://github.com/bytecodealliance/wasmtime/actions/workflows/bump-version.yml
@ -167,5 +154,19 @@ the runbook is merged.
Note that the actual security fixes should be merged either before or as
part of this PR.
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.
## 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 `main` which need to write an entry in
`RELEASES.md`.
* When the `main` branch gets a version the `RELEASES.md` file is emptied and
replaced with `ci/RELEASES-template.md`. An entry for the upcoming release is
added to the bulleted list at the bottom.
* (realistically) After a `release-X.Y.Z` branch 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`

Loading…
Cancel
Save