update-existing-branch

# Update Existing Branch Use this skill when the milestone branch set already exists and contains drafted markdown, `features.json`, reviewer comments, or human edits. The branch set is the base branch plus its per-component branches as defined in [`release-notes/references/pr-layout.md`](../release-notes/references/pr-layout.md). This is the **incremental rerun** stage of the release-notes pipeline. It is the branch-maintenance equivalent of what `editorial-scoring` is for scoring: the canonical place to describe how follow-up runs should behave. ## Purpose Treat the existing branch set as the **working baseline**, not as a blank slate. The goal is to: 1. refresh shipped-change data only when the preview actually moved forward 2. score and write the **delta**, not the whole release again 3. preserve human edits and reviewer-driven rewrites on every component branch 4. integrate new material into the current story cleanly ## Inputs Read these before making changes: 1. the current base branch and its PR 2. every per-component branch and its PR 3. the existing `changes.json`, `features.json`, and `build-metadata.json` on the base branch 4. the existing markdown files on each component branch 5. unresolved PR review comments and discussion threads on every PR in the set ## Which branch holds what Respect this invariant on every rerun: | Artifact | Lives on | | -------- | -------- | | `changes.json`, `features.json`, `build-metadata.json` | base branch only | | `README.md` | base branch preallocates entries; each component branch links only its own entry alongside the matching file | | `{component}.md` (e.g. `aspnetcore.md`, `runtime.md`) | matching component branch only | ## Process ### 1. Check whether the preview moved forward Determine whether later `dotnet/dotnet` codeflow commits landed for the same preview branch or tag since the last run. If the relevant VMR ref moved forward, regenerate `changes.json` on the base branch. If it did not, keep the current file and focus on editorial fixes and comment responses on the component branches. Typical signals: - later commits on `dotnet/dotnet` for `release/<major>.0.1xx-previewN` - a newer release-branch head than the one captured in `build-metadata.json` - new source-manifest commits for a component already discussed in the draft ### 2. Compute a delta from the existing files If you refreshed `changes.json`, compare the old and new files by stable `id`. Classify changes as: - **added** — new shipped items not seen in the last run - **changed** — same `id`, but new evidence, labels, revert state, or reviewer context changes the treatment - **removed or superseded** — no longer relevant to the current build story, or later evidence shows the original interpretation was wrong - **unchanged** — keep the prior editorial work Do **not** treat a refreshed `changes.json` as permission to restart the whole release from zero. ### 3. Merge into the existing `features.json` When `features.json` already exists, use it as the editorial baseline and merge the delta into it on the base branch. Preserve prior annotations for unchanged entries, including: - `score` - `score_reason` - `score_breakdown` - `breaking_changes` - `reverted_by` / `reverts` - useful human notes or hand-tuned annotations Only rescore: - newly added entries - materially changed entries - earlier entries that reviewers explicitly questioned or that new evidence disproved This should feel like a **delta merge**, not a full rescore. ### 4. Update markdown in place Use the current draft as the starting point. Prefer **integration** over duplication. For each component affected by the delta, update **only** that component's markdown and its own README entry on **its** branch. Before editing, merge the base branch into the component branch so the latest metadata and already-merged index links are available in your working tree; don't touch component branches you aren't editing this run. Add a link only when adding the matching component file; keep other pending entries unlinked and preserve links already merged. Examples: - on the runtime branch, add a new GC item into the existing **Garbage Collection Performance Improvements** section in `runtime.md` - on the libraries branch, extend an existing **Unsafe Evolution** block in `libraries.md` instead of creating a second heading - move a newly demoted item into **Bug fixes** instead of deleting the story without explanation Keep the existing structure when it still works. Add a new top-level section only when the delta introduces a genuinely new story. When the target build changes or an incremental API diff becomes available, review it for [upgrade-impacting changes](../release-notes/references/api-verification.md#review-incremental-api-diffs-for-preview-upgrades), including any API-diff review left pending on the base PR. Put verified guidance in the affected component's version-to-version or preview-only section as appropriate, without rewriting unrelated notes. Incorporate newly published compatibility guidance even if the build has not changed. ### 5. Treat review comments as required inputs Unresolved PR comments are part of the spec for the next run, on every PR in the set. - read them before rewriting anything - answer factual questions with evidence from `changes.json`, VMR refs, API verification, or the final build - update the markdown when the reviewer is right - if the reviewer is directionally right but the current build still contains the feature, explain the milestone and branch context clearly ### 6. Default outcome For an existing release-notes branch set, the normal loop is: 1. refresh `changes.json` only if the preview moved forward 2. merge the delta into `features.json` 3. update the existing markdown in place 4. respond to comments and questions Before finalizing the refreshed draft, run [`review-release-notes`](../review-release-notes/SKILL.md) against the merged `features.json`, `changes.json`, and component files on their own branches until merged. Resolve noteworthy omissions or record the editorial reason in the corresponding `features.json` entry's `score_reason` on the base branch. This keeps the branch set stable for reviewers and avoids throwing away already curated editorial work.