Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

Add some notes about writing release notes (#14704)

Alex Crichtona59a82daf2e3
diff --git a/docs/contributing-release-process.md b/docs/contributing-release-process.md
index 0646f66d54..2d44914643 100644
--- a/docs/contributing-release-process.md
+++ b/docs/contributing-release-process.md
@@ -179,6 +179,57 @@ 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`
+### Writing release notes for a major release
+
+Release notes for a major release are written on the `release-X.0.0` branch some
+time between the branch being cut and the release itself. To get a log of all
+commits to document for the 50.0.0 release, use a command like:
+
+```console
+$ git log --oneline \
+ $(git merge-base origin/release-49.0.0 origin/release-50.0.0)..origin/release-50.0.0
+```
+
+Commits are manually reviewed to typically go into one of three buckets in the
+release notes section: Added, Changed, or Fixed. Use your best judgement for
+deciding what gets a release note and what doesn't, there's no strict guidelines
+at this time. In general internal changes like those for CI aren't documented,
+and if a fix for something is particularly niche then it's also not always
+documented. Erring on the side of documenting it is fine though.
+
+Stylistically release note entries look like:
+
+* Each entry is assigned a bullet, blank lines between entries.
+* A summary sentence is written with a link to the PR(s) below that. Note that
+ the link must be a manual markdown link, #12345 is not enough.
+* Security fixes link to their advisory rather than the PR.
+
+For example:
+
+```markdown
+### Added
+
+* Wasmtime now supports the WebAssembly compact imports proposal, disabled by
+ default, via `Config::wasm_compact_imports`.
+ [#14335](https://github.com/bytecodealliance/wasmtime/pull/14335)
+
+### Changed
+
+* Wasmtime now requires Rust 1.97.0 to compile.
+ [#14466](https://github.com/bytecodealliance/wasmtime/pull/14466)
+```
+
+The release date line, `Unreleased.`, is left as-is as it's automatically
+updated during the release process.
+
+### Writing release notes for a patch release
+
+Patch release notes are written as part of each backport PR, or alternatively
+in the PR generated by the `release-patch` process. A new `## X.Y.Z` section is
+added at the top of `RELEASES.md`. Be sure to include the `----` separator
+between releases as this is used in the release automation to determine what
+notes go into the github release.
+
## Keeping Old release branch CI up-to-date
Over time CI configuration goes out of date and may need to be updated. The