Skip to content

Commit c740515

Browse files
fix(release): keep release bodies within GitHub's size limit
Finalize sets the release body after the stable tag, the api/apps/v1alpha1 tag and the release-X.Y fast-forward already exist, so a body GitHub refuses fails the step with the release still a draft, and the image retag and chart publish behind it never run. GitHub's web UI cut the v1.7.0-rc.2 changelog at about 125000 characters, and the v1.7.0 changelog is 259,026. A release can now carry a short hand-written docs/releasenotes/<tag>.md that becomes its body, while the changelog stays the full record. Both finalize and update-releasenotes take the release notes when they have content and the changelog otherwise, and hold the body to 100000 bytes. Bytes are never fewer than characters, and the margin makes GitHub's exact limit, and its answer to an oversized body, irrelevant. Over the limit, finalize publishes a one-line link to the changelog on the tag instead, and the sync leaves the published body alone: the tags.yaml backstop brings a changelog to main without its release notes, and the sync would otherwise replace them. A release without release notes whose changelog is under the limit still gets its changelog byte for byte. Assisted-by: LLM Signed-off-by: Myasnikov Daniil <[email protected]> (cherry picked from commit b502a92)
1 parent 315b335 commit c740515

5 files changed

Lines changed: 278 additions & 78 deletions

File tree

‎.github/workflows/pull-requests-release.yaml‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -419,24 +419,51 @@ jobs:
419419
// Reading the file here is both race-free and branch-agnostic;
420420
// update-releasenotes.yaml remains for later maintainer edits and
421421
// manual re-syncs.
422+
//
423+
// docs/releasenotes/${tag}.md, a short hand-written summary for a
424+
// release whose changelog is too long to read on the release page,
425+
// is the body when it has content; the changelog otherwise.
426+
//
427+
// The tags above already exist, so a body GitHub refuses would
428+
// strand a half-promoted release. GitHub's web UI cut the
429+
// v1.7.0-rc.2 changelog at about 125000 characters. MAX_BODY_BYTES
430+
// counts bytes, which are never fewer than characters, and sits 25
431+
// percent under that figure, so neither the difference nor an
432+
// imprecise limit matters, and GitHub's answer to an oversized
433+
// body is never relied on. update-releasenotes.yaml uses the same
434+
// constant.
422435
const fs = require('fs');
436+
const MAX_BODY_BYTES = 100000;
423437
const changelogPath = `docs/changelogs/${tag}.md`;
424-
let body;
425-
if (fs.existsSync(changelogPath)) {
426-
const raw = fs.readFileSync(changelogPath, 'utf8');
438+
let sourcePath;
439+
let raw;
440+
for (const candidate of [`docs/releasenotes/${tag}.md`, changelogPath]) {
441+
if (!fs.existsSync(candidate)) continue;
442+
raw = fs.readFileSync(candidate, 'utf8');
427443
// Last line of defence before the body becomes public and
428444
// immutable-by-convention. promote-rc.yaml validates the changelog
429445
// structurally, but it can also arrive by hand-commit, and an
430446
// empty or whitespace-only file here would blank the release notes
431447
// more thoroughly than publishing the draft's body would.
432448
if (raw.trim().length === 0) {
433-
console.log(`::warning::${changelogPath} is empty or whitespace-only — refusing to use it as the release body for ${tag}. Publishing with the draft's existing body instead.`);
449+
console.log(`::warning::${candidate} is empty or whitespace-only — not using it as the release body for ${tag}.`);
450+
continue;
451+
}
452+
sourcePath = candidate;
453+
break;
454+
}
455+
let body;
456+
if (!sourcePath) {
457+
console.log(`::warning::No usable docs/releasenotes/${tag}.md or ${changelogPath} in the merge commit — publishing ${tag} with the draft's existing body. Add the changelog and re-run 'Update Release Notes' to backfill it.`);
458+
} else {
459+
const bytes = Buffer.byteLength(raw, 'utf8');
460+
if (bytes > MAX_BODY_BYTES) {
461+
body = `The release notes for ${tag} are too long for a GitHub release description; the full changelog is [${changelogPath}](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/${tag}/${changelogPath}).`;
462+
console.log(`::warning::${sourcePath} is ${bytes} bytes, over MAX_BODY_BYTES (${MAX_BODY_BYTES}) — publishing ${tag} with a link to ${changelogPath} instead.`);
434463
} else {
435464
body = raw;
436-
console.log(`📝 Release body from ${changelogPath} (${body.length} bytes)`);
465+
console.log(`📝 Release body from ${sourcePath} (${bytes} bytes)`);
437466
}
438-
} else {
439-
console.log(`::warning::${changelogPath} not found in the merge commit — publishing ${tag} with the draft's existing body. Add the changelog and re-run 'Update Release Notes' to backfill it.`);
440467
}
441468
442469
// Publish the release

‎.github/workflows/update-releasenotes.yaml‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,12 @@ on:
99
# (tags.yaml generate-changelog) merges or when a maintainer edits an
1010
# existing changelog. The v* glob deliberately skips template.md /
1111
# patch-template.md in the same directory. Every other main push left this
12-
# job scanning the latest 30 releases for nothing.
12+
# job scanning the latest 30 releases for nothing. A docs/releasenotes/v*.md
13+
# file, when it has content, is the body in place of its changelog, so it
14+
# triggers the sync too.
1315
paths:
1416
- 'docs/changelogs/v*.md'
17+
- 'docs/releasenotes/v*.md'
1518
# Manual re-sync hatch: re-run the changelog -> release-body sync without
1619
# touching a changelog file (e.g. if a release body drifted out of sync).
1720
workflow_dispatch:
@@ -47,6 +50,8 @@ jobs:
4750
const path = require('path');
4851
4952
const changelogDir = 'docs/changelogs';
53+
// Same limit and reason as MAX_BODY_BYTES in pull-requests-release.yaml.
54+
const MAX_BODY_BYTES = 100000;
5055
5156
// Get releases from first page
5257
const releases = await github.rest.repos.listReleases({
@@ -61,7 +66,12 @@ jobs:
6166
for (const release of releases.data) {
6267
const tag = release.tag_name;
6368
const changelogFile = `${tag}.md`;
64-
const changelogPath = path.join(changelogDir, changelogFile);
69+
// docs/releasenotes/<tag>.md is the body when it has content, as
70+
// in finalize; the changelog otherwise.
71+
const notesPath = path.join('docs/releasenotes', changelogFile);
72+
const changelogPath = fs.existsSync(notesPath) && fs.readFileSync(notesPath, 'utf8').trim()
73+
? notesPath
74+
: path.join(changelogDir, changelogFile);
6575
6676
console.log(`\nProcessing release: ${tag}`);
6777
@@ -85,6 +95,16 @@ jobs:
8595
continue;
8696
}
8797
98+
// Finalize publishes a link in place of a body this long. Never
99+
// here: a changelog that reaches main without its release notes
100+
// (the tags.yaml backstop ports only the changelog) would replace
101+
// a good published body with it.
102+
const bytes = Buffer.byteLength(changelogContent, 'utf8');
103+
if (bytes > MAX_BODY_BYTES) {
104+
console.log(`::warning::${changelogPath} is ${bytes} bytes, over MAX_BODY_BYTES (${MAX_BODY_BYTES}); leaving the body of release ${tag} as it is.`);
105+
continue;
106+
}
107+
88108
// Check if content is already up to date
89109
const currentBody = release.body || '';
90110
if (currentBody.trim() === changelogContent.trim()) {

‎docs/release.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -300,7 +300,7 @@ Reviewer checklist for the `chore(release): promote vX.Y.Z-rc.N -> vX.Y.Z` PR:
300300
- [ ] No accidental config drift (a value file you don't recognize).
301301
- [ ] If any chart bumped, check the new digest pulls — `crane manifest ghcr.io/cozystack/cozystack/<name>@<digest>` should return.
302302
- [ ] Build artifacts on the draft release page exist and match the expected count.
303-
- [ ] The PR includes `docs/changelogs/vX.Y.Z.md`, it has content, and the entries match the commit range (see [Changelog pre-publish verification](#changelog-pre-publish-verification)). If the PR body carries the ⚠️ "No changelog in this PR" line, resolve that before merging — finalize publishes this file as the release body.
303+
- [ ] The PR includes `docs/changelogs/vX.Y.Z.md`, it has content, and the entries match the commit range (see [Changelog pre-publish verification](#changelog-pre-publish-verification)). If the PR body carries the ⚠️ "No changelog in this PR" line, resolve that before merging — finalize publishes this file as the release body, unless the PR also carries `docs/releasenotes/vX.Y.Z.md` (see [Phase 6](#phase-6--update-releasenotesyaml-sync-github-release-body)).
304304

305305
### Phase 5 — `pull-requests-release.yaml` (finalize)
306306

@@ -310,13 +310,15 @@ Fires on merge of a PR that is merged, carries the `release` label, and is autho
310310
2. **Create the tag at the merge commit** (write-once). The merge commit of `Prepare release vX.Y.Z` did not exist before the PR opened, so there is nothing to move — the tag is created here for the first time. A pre-existing tag at a different commit fails the step loudly rather than being force-moved (see [Tag immutability](#tag-immutability)). The checkout uses `persist-credentials: false` so this push authenticates as the **CI app** (via `git remote set-url`), not the default `GITHUB_TOKEN` — a `GITHUB_TOKEN` push creates no workflow run, so a persisted-credential push would silently skip `tags.yaml` entirely and its stable-tag backstops (`generate-changelog`, `update-website-docs`) would never fire.
311311
3. **Cut the `api/apps/v1alpha1/vX.Y.Z` Go-module tag** (write-once, stable only) at the same commit, so Go consumers of `api/apps/v1alpha1` get the release. Moved here from `tags.yaml`, whose `prepare-release` body is skipped for a promoted stable (the draft already exists).
312312
4. **Ensure the maintenance branch `release-X.Y` exists** at the tag commit. Since the rc freeze creates it, this is normally a no-op fast-forward — the merge commit is already the branch tip. Still created if missing; updated fast-forward-only — a non-fast-forward update warns and is left for a maintainer rather than being force-updated.
313-
5. **Publish the draft release**, with `docs/changelogs/vX.Y.Z.md` from the merge commit as its body (an absent or whitespace-only file warns and leaves the draft's body in place, rather than publishing blank notes). `make_latest` is computed against published-non-prerelease tags: prereleases stay `false`; tags older than the current max stay `false` (and the current max is force-restored to `latest` if necessary, so an older patch tag cut after a newer minor won't downgrade `latest`).
313+
5. **Publish the draft release**, with `docs/releasenotes/vX.Y.Z.md`, or without it `docs/changelogs/vX.Y.Z.md`, from the merge commit as its body (absent or whitespace-only files warn and leave the draft's body in place, rather than publishing blank notes, and a body over 100000 bytes is published as a link, see [Phase 6](#phase-6--update-releasenotesyaml-sync-github-release-body)). `make_latest` is computed against published-non-prerelease tags: prereleases stay `false`; tags older than the current max stay `false` (and the current max is force-restored to `latest` if necessary, so an older patch tag cut after a newer minor won't downgrade `latest`).
314314
6. **Retag the verified packages candidate and rc container images to stable** by digest (`hack/promote-retag.sh`, no container rebuild) and **publish the stable `cozy-installer` chart**. `:latest` (on both the images and the chart) moves only when this release's `make_latest` was `true` — the same decision as step 5, so the release's `latest` and the images' `:latest` never disagree. The chart is packaged with `platformVersion` stamped into its default values so the documented `helm --install --version X.Y.Z` path reports the stable version.
315315

316316
### Phase 6 — `update-releasenotes.yaml` (sync GitHub Release body)
317317

318318
Fires on pushes to `main` that touch `docs/changelogs/v*.md`. Reads each `docs/changelogs/vX.Y.Z.md` and PATCHes the matching GitHub Release's `body` if it differs. Since Phase 5 now sets the body directly from the merge commit, this is no longer on the critical path — it covers later **edits** to a published changelog, the backstop PR landing a changelog that reached `main` after the fact, and manual re-syncs via `workflow_dispatch`. It only watches `main`, which is why finalize (not this job) is what populates a release promoted onto `release-X.Y` — since the freeze, that is every release rather than only a patch.
319319

320+
The release body is `docs/releasenotes/vX.Y.Z.md` when it exists and is not blank, otherwise the changelog, which stays the full record either way, and a push to `main` touching either file fires this sync. Finalize sets the body after the stable tags exist, where a body GitHub refuses would strand the release, so at publish time a body over 100000 bytes is replaced by a one-line link to `docs/changelogs/vX.Y.Z.md` on the tag, with a warning in the run's log. This sync never writes that link: it warns and leaves such a release's body as it is. The `tags.yaml` backstop ports only the changelog to `main`, so release notes have to be added to `main` as well, otherwise the sync falls back to the changelog and replaces the release notes with it whenever the changelog fits.
321+
320322
## Stable tags come from rc promotion
321323

322324
A stable `vX.Y.Z` is created only by **promoting an existing release-candidate** that already passed e2e — never by rebuilding and never by a cron.

0 commit comments

Comments
 (0)