/
/
/
1# Release Notes Generation
2
3Release notes are generated from the exact `source_sha` selected at the start of a
4release. Branch names determine the channel source, but they are never used as the notes
5comparison head after the SHA is captured.
6
7## Previous-tag selection
8
9The workflow discovers prior releases from Git tags:
10
11| Channel | Previous tag |
12|---|---|
13| Stable | Latest `X.Y.Z` tag |
14| Beta | Latest `X.Y.ZbN` or `X.Y.ZrcN` tag |
15| RC1 | Latest `X.Y.ZbN` tag |
16| RC2+ | Previous RC for the same base version, falling back to the latest beta |
17| Nightly | Latest `X.Y.Z.devN` tag |
18
19The version currently being prepared is always excluded. This matters for retries and
20for deleted release records whose Git tag still exists.
21
22For linear histories, pull requests come from the commits between the previous tag and
23`source_sha`. A stable minor branch can diverge from the previous stable patch branch.
24In that case, the generator uses the merge base as its cutoff and excludes pull requests
25that already shipped on the old patch branch.
26
27## Note contents
28
29`.github/release-notes-config.yml` defines label categories, exclusions, formatting, and
30contributors. The generator:
31
321. Finds merged pull requests represented in the exact Git comparison.
332. Excludes pull requests merged before the comparison cutoff or already released on a
34 diverged stable patch branch.
353. Categorizes changes using the release-notes configuration.
364. Extracts notes from frontend dependency-update pull requests in the same comparison.
375. Merges and deduplicates server and frontend contributors.
386. Places manually supplied important notes first.
39
40The resulting body is finalized on the matching draft before publication. Reruns may
41refresh draft notes, but release assets and the source SHA must remain exact. After
42publication, the release is verified as immutable and release/asset attestations are
43checked before downstream promotion.
44
45## Verification
46
47The focused tests cover linear and diverged comparisons:
48
49```bash
50pytest tests/test_generate_release_notes.py tests/scripts/test_release_workflow.py
51```
52
53To inspect a pending comparison manually, use the source SHA reported by auto-release:
54
55```bash
56git log PREVIOUS_TAG..SOURCE_SHA --oneline
57```
58
59For a diverged stable tag, inspect both sides from their merge base:
60
61```bash
62base=$(git merge-base PREVIOUS_TAG SOURCE_SHA)
63git log "$base..SOURCE_SHA" --oneline
64git log "$base..PREVIOUS_TAG" --oneline
65```
66