From 00301eb64f35152fb2358fb226cd1ae067d77eeb Mon Sep 17 00:00:00 2001 From: iancooper Date: Sun, 27 Sep 2026 14:40:41 +0100 Subject: [PATCH 1/2] docs: a port's PR title is its CHANGELOG entry Runbook Step 4.5 said to append a CHANGELOG.md entry by hand, but the file is generated at release by eng/update-changelog.ps1 from the GitHub release notes (PR titles), inserted below . There is no unreleased section to append to. Decided during upstream sync #1 (#28). Co-Authored-By: Claude Opus 5.5 (1M context) --- .agent_instructions/upstream_sync.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.agent_instructions/upstream_sync.md b/.agent_instructions/upstream_sync.md index 1e15dc28..ea44b0ed 100644 --- a/.agent_instructions/upstream_sync.md +++ b/.agent_instructions/upstream_sync.md @@ -153,8 +153,14 @@ For each commit triaged "port": defer the port. 4. Reference the upstream SHA in the commit message, e.g. `Port App-vNext/Polly@482bdf82: return null from FaultGenerator when no fault is generated`. -5. Append a `CHANGELOG.md` entry in Fences' own voice. Never rewrite the existing history in that - file — Polly's entries for 8.7.0 and below stay exactly as they are. +5. Give the PR a user-facing title in Fences' own voice. **That title is the `CHANGELOG.md` + entry**, so do not edit `CHANGELOG.md` by hand. At release, `after-release.yml` runs + `eng/update-changelog.ps1`, which builds the version's section from the GitHub release notes + (one bullet per merged PR title) and inserts it below ``. There is no + unreleased section to append to. Describe what changes for a Fences user, e.g. "Return null + from FaultGenerator when no fault is generated", not "Port App-vNext/Polly@482bdf82"; the + upstream SHA belongs in the commit message (step 4) and the PR body. Never rewrite the existing + history in `CHANGELOG.md`: Polly's entries for 8.7.0 and below stay exactly as they are. 6. Follow the normal verification gates in `CLAUDE.md` before merging: analyser-clean build, tests passing, a `.PublicAPI/` entry if the change is public, mutation score not regressed. From 36608556d91f10ac2cbeb88fb635d3903ac0dc0e Mon Sep 17 00:00:00 2001 From: iancooper Date: Sun, 27 Sep 2026 14:56:32 +0100 Subject: [PATCH 2/2] docs: amend ADR 0003 D8, a port's PR title is its CHANGELOG entry D8 said a port adds a CHANGELOG.md entry, but the file is generated at release from merged PR titles and has no unreleased section to add to. D8 now matches runbook Step 4.5, with an amendment note under Status. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/adr/0003-upstream-polly-sync-process.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/adr/0003-upstream-polly-sync-process.md b/docs/adr/0003-upstream-polly-sync-process.md index 984e5eac..1aa9c4b1 100644 --- a/docs/adr/0003-upstream-polly-sync-process.md +++ b/docs/adr/0003-upstream-polly-sync-process.md @@ -20,6 +20,10 @@ Date: 2026-09-20 Accepted +Amended 2026-09-27: D8 originally said a port "adds a `CHANGELOG.md` entry". `CHANGELOG.md` is +generated at release from pull request titles, with no unreleased section to add to, so D8 now makes +the port's pull request title the entry. Found during the first sync (#28). + ## Context ADR 0002 forked `App-vNext/Polly` at commit `47e3b41` (Polly 8.7.0). A fork taken at one commit is @@ -56,7 +60,7 @@ The gate and the steps: | D5 | A commit whose message matches Dependabot's `Bump from to ` convention defaults to "skip" without individual review, because Fences tracks its own dependencies independently through its own Dependabot configuration. Every other commit needs a person to bucket it. | | D6 | Findings land in one recurring tracking issue, updated at each sync, rather than a new issue written from scratch: the licence-gate result, the commits since the last sync, and the skip/port/needs-review buckets. | | D7 | A ported commit rebrands namespaces, assemblies and package IDs to `Paramore.Fences.*` per ADR 0002's D1, but otherwise keeps Polly's public types, members and signatures unchanged, so the ADR 0002 find/replace promise holds for every sync, not only the original fork. Where an upstream commit cannot be ported without breaking that compatibility, the port does not quietly diverge to fit: the divergence is recorded as a code comment at the point it occurs and flagged in the tracking issue for a maintainer to decide. | -| D8 | A ported commit also references the upstream SHA in its commit message and adds a `CHANGELOG.md` entry in Fences' own voice. `CHANGELOG.md` itself is never rewritten. | +| D8 | A ported commit also references the upstream SHA in its commit message, and its pull request's title, written in Fences' own voice, is its `CHANGELOG.md` entry: the release process generates each version's section from merged pull request titles, so ports do not edit `CHANGELOG.md` by hand. The existing history in `CHANGELOG.md` is never rewritten. | | D9 | `polly-upstream` advances to the SHA just triaged at the end of each sync, so D4's diff starts there next time. | | D10 | The runbook for D1 to D9 lives in `.agent_instructions/upstream_sync.md`, not in this ADR or in session state, so a contributor or agent can run a sync without re-deriving the process. |