<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-11-01-1-pull-requests-touch-no-shared-generated-files-and-land-through-a-merge-queue/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-11-01-1-pull-requests-touch-no-shared-generated-files-and-land-through-a-merge-queue/</id>
  <title>ADR: pull requests touch no shared generated file and land through a merge queue</title>
  <updated>2026-11-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-11-01-1-pull-requests-touch-no-shared-generated-files-and-land-through-a-merge-queue/"/>
  <summary>Changelog entries become per-PR fragments, the docs index regenerates on main through a bot PR, and main merges through a GitHub merge queue.</summary>
  <content type="html">&lt;h2 id=&quot;pull-requests-touch-no-shared-generated-file-and-land-through-a-merge-queue&quot;&gt;Pull requests touch no shared generated file and land through a merge queue&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-11-01). Operator rulings of 2026-11-01 on the landing-bottleneck brief.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-11-01&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The 2026-10-31/11-01 landing run: 22 PRs merged in about 24.5 hours, a 6-hour Actions deadlock (#6961, #6963), and duplicate changelog entries from rebases that kept both sides of a conflict.&lt;/li&gt;
&lt;li&gt;Dedicated bot token: #6986 (interim use of &lt;code dir=&quot;auto&quot;&gt;CHARTER_SHARD_RECAPTURE_TOKEN&lt;/code&gt;, see Decision 2).&lt;/li&gt;
&lt;li&gt;Amends &lt;a href=&quot;/adr/3.x/2026-09-23-1-auto-merge-required-checks-gate/&quot;&gt;ADR 2026-09-23-1&lt;/a&gt; (the required checks gate auto-merge; see Decision 3).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Landing throughput was about one PR an hour, and CI latency was not the main reason. Nearly every PR
edited the same files:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt; (an &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; entry and the frontmatter &lt;code dir=&quot;auto&quot;&gt;updated:&lt;/code&gt; key);&lt;/li&gt;
&lt;li&gt;the generated &lt;code dir=&quot;auto&quot;&gt;docs/development/docs-retrieval-index.yaml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;docs/development/page-inventory.yaml&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;for a new ADR, the era table in &lt;code dir=&quot;auto&quot;&gt;docs/adr/&amp;#x3C;era&gt;/index.md&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Each merge to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; therefore put every other in-flight PR in conflict. Each conflicted PR needed a
rebase and a full CI re-run, 40 to 60 minutes under load. With four PRs in flight, every merge cost
about three wasted CI cycles, and the waste grew with the number of PRs in flight. Rebases that
kept both sides of a changelog conflict re-added duplicate entries three times and once left a second
&lt;code dir=&quot;auto&quot;&gt;updated:&lt;/code&gt; key.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;1-changelog-entries-are-per-pr-fragments&quot;&gt;1. Changelog entries are per-PR fragments&lt;/h3&gt;
&lt;p&gt;A pull request adds &lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&amp;#x3C;id&gt;.&amp;#x3C;section&gt;.md&lt;/code&gt; and never edits
&lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt;.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;id&gt;&lt;/code&gt; is the PR number; before the PR exists, the issue number plus a branch slug, renamed once
the PR number is known. Lowercase letters, digits and &lt;code dir=&quot;auto&quot;&gt;-&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;section&gt;&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;breaking&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upgrade-notes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;added&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;changed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fixed&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;internal&lt;/code&gt;, the six
&lt;code dir=&quot;auto&quot;&gt;###&lt;/code&gt; headings of &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt;, in that order.&lt;/li&gt;
&lt;li&gt;The content is the entry exactly as it reads in the changelog, with no heading and no open code fence.&lt;/li&gt;
&lt;li&gt;The style guard (&lt;code dir=&quot;auto&quot;&gt;scripts/docs/check_changelog_style.py&lt;/code&gt;) and the spelling check
(&lt;code dir=&quot;auto&quot;&gt;scripts/docs/check_spelling.py&lt;/code&gt;) run on every fragment and report at the fragment’s own lines.&lt;/li&gt;
&lt;li&gt;At release time &lt;code dir=&quot;auto&quot;&gt;python -m scripts.release.changelog_fragments assemble --write&lt;/code&gt; folds the fragments
into &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt;, after the existing entries, sets &lt;code dir=&quot;auto&quot;&gt;updated:&lt;/code&gt; and deletes them.
&lt;code dir=&quot;auto&quot;&gt;validate_release.py&lt;/code&gt; refuses a tag, or a release-cut branch, while any fragment remains.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fragments are not docs pages.&lt;/strong&gt; Every other &lt;code dir=&quot;auto&quot;&gt;docs/**/*.md&lt;/code&gt; file needs frontmatter, a row in the
page inventory and an entry in the docs retrieval index. &lt;code dir=&quot;auto&quot;&gt;scripts/docs/_page_scope.py&lt;/code&gt; is the one
authority for the page set and leaves &lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&lt;/code&gt; out, so a fragment touches no
shared file. The docs site build excludes the directory (&lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The operator chose &lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&lt;/code&gt; over a root &lt;code dir=&quot;auto&quot;&gt;changelog.d/&lt;/code&gt;, keeping the fragments
beside the changelog they feed, at the cost of the page-scope exclusion.&lt;/p&gt;
&lt;h3 id=&quot;2-the-docs-retrieval-index-and-its-siblings-regenerate-on-main-through-a-bot-pr&quot;&gt;2. The docs retrieval index and its siblings regenerate on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, through a bot PR&lt;/h3&gt;
&lt;p&gt;PRs no longer regenerate &lt;code dir=&quot;auto&quot;&gt;docs-retrieval-index.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;page-inventory.yaml&lt;/code&gt; or the ADR era tables.
After a merge to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; that touches &lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt; (and on a daily schedule as a backstop), a workflow
regenerates all three and opens or updates one PR on a fixed branch, &lt;code dir=&quot;auto&quot;&gt;ci/regen-docs-index&lt;/code&gt;, the way
the shard-timings recapture already does. The per-PR gate checks that the index regenerates cleanly
from the tree instead of comparing it with a committed copy that is expected to lag.&lt;/p&gt;
&lt;p&gt;The bot uses a PR, not a commit to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;: it needs no branch-protection exception and runs the normal
required checks. It authenticates with the existing &lt;code dir=&quot;auto&quot;&gt;CHARTER_SHARD_RECAPTURE_TOKEN&lt;/code&gt; PAT. &lt;strong&gt;Sharing that
token is interim&lt;/strong&gt;; a dedicated secret is tracked in #6986.&lt;/p&gt;
&lt;p&gt;Generating the index at build or query time (measured about 1.3 s per query, and the generator would
have to move into &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;) and splitting it into about 915 per-page files were rejected. The wheel has
never shipped the index, so neither choice changes anything for installed users.&lt;/p&gt;
&lt;h3 id=&quot;3-main-merges-through-githubs-merge-queue&quot;&gt;3. &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; merges through GitHub’s merge queue&lt;/h3&gt;
&lt;p&gt;The queue tests each PR on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; plus the PRs ahead of it and rebase-merges it when the required
checks pass there, replacing the manual rebase-and-re-run loop.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ci-modules.yml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt;, which produce the three required checks
(&lt;code dir=&quot;auto&quot;&gt;router gate&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CI Modules gate&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Clean install verification&lt;/code&gt;), trigger on &lt;code dir=&quot;auto&quot;&gt;merge_group&lt;/code&gt;. No optional
workflow joins the queue: path-filtered ones would run on every group.&lt;/li&gt;
&lt;li&gt;The changed-files and prose-scan steps diff a queue run against &lt;code dir=&quot;auto&quot;&gt;merge_group.base_sha&lt;/code&gt;, so it stays
path-scoped. CI Aggregate skips queue runs. CI Fleet Verdict keys its concurrency on the source
event, so a queue run never cancels the push-to-main verdict of the same commit.&lt;/li&gt;
&lt;li&gt;Repository settings (operator): require the merge queue on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;; merge method rebase; only merge
non-failing pull requests; build concurrency 3; group size minimum 1 and maximum 3; wait time
5 minutes; status-check timeout 90 minutes.&lt;/li&gt;
&lt;li&gt;Operator prerequisite: the external fleet stops pushing to queued PRs. A push removes a PR from the
queue and rebuilds every group behind it.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This amends ADR 2026-09-23-1. The three required checks and &lt;code dir=&quot;auto&quot;&gt;strict: false&lt;/code&gt; stand, and auto-merge
now queues a PR instead of merging it.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Two PRs that each add a changelog fragment or edit unrelated docs no longer conflict.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty docs query&lt;/code&gt; on a branch can lag by the pages merged since the last bot PR.&lt;/li&gt;
&lt;li&gt;The release gains one step, assembling the fragments, enforced by &lt;code dir=&quot;auto&quot;&gt;validate_release.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Every PR runs the required checks twice, on the PR and in the queue. The queue run is path-scoped.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;packs/internal&lt;/code&gt; (in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-open-packs&lt;/code&gt;) still tells agents to edit &lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt; and to
regenerate the index; that doctrine is updated there and the pin bumped in a follow-up.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
