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. 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. |