Zum Inhalt

A new record takes the number of its pull request or of its issue, and the release writes the index

  • Status: accepted
  • Date: 2026-11-18

Context

A decision got a record in docs/decisions/ with the next free number and a row at the end of the index, docs/decisions/README.md. Two pull requests that were open at the same time took the same number and added their row at the same place. Once the first one merged, the second one conflicted with main in the index: GitHub marked it DIRTY and ran no checks, and the branch bot could not update it and left it for a person. Decision 0135 expected the step Records of decisions to fail on the clash after the branch bot's merge; the conflict of the index came first.

From 2026-11-10 to 2026-11-17, 42 of the 135 merged pull requests of the blueprint added a record, and 19 of them renumbered it before they merged, 24 times in all, each time with a merge of main by hand and a rename in up to twenty files (#1033). One push to such a pull request starts 22 to 26 workflow runs. The repositories that follow the blueprint use the same scheme from the template.

Options

  1. A record without a number, numbered by a bot at the merge or the release, as the fragments of the changelog are (decision 0018). The code, workflows and pages of the same pull request would cite it by a placeholder, which a bot would rewrite on main afterwards, in .github/workflows/ and blueprint/ too, which decision 0142 keeps away from a bot's commit that nobody reads.
  2. A generated index, and a fix bot that gives a clashing record the next number in every reference. The generated index ends the conflict, but the rename fails on the same rule of decision 0142, and decision 0135 left which record moves to its author.
  3. A date or a title in place of a number. Ten records merged on 2026-11-17 alone, so a date clashes as well; a title is too long to cite, loses the order of the folder, and renaming the records would break the links of the released notes.
  4. The number of the pull request, and an index that the release writes. GitHub gives each pull request a number that nothing else gets, so two open pull requests never take the same one, and a pull request that leaves the index alone conflicts with no other one there.
  5. The number of the pull request or of an issue that it fixes. GitHub counts issues and pull requests together, so an issue's number is no pull request's either, and it is known before the pull request exists.

Decision

Option 5, which holds option 4: a new record is docs/decisions/<number>-<its-title>.md, the number of its pull request or of an issue that the pull request closes with Fixes #…, Fixes owner/repo#… or the link to the issue in its description, and it is cited by that number, as this record is decision 1033 after the issue that its pull request fixes.

  • Why the issue's number too: the number of a pull request is known only once it is open, so a record that takes it costs a push before the first review, and each push starts every check again. Most pull requests that make a decision fix an issue that was filed before, whose number is known when the work starts. Two pull requests that both close one issue and both add a record clash; the step names the clash once main is merged, and the second one takes the number of its pull request.
  • The check: blueprint.py decisions fails when two records share a number, when a file of the folder is no record, and on a wrong row of the index: a row twice, a row of a file that doesn't exist, a row with another number than its file and rows out of order, now by the value of the number, so that 1033 follows 0181 and 10000 follows 9999. The rule against gaps is gone. In the CI of a pull request, a record whose number main doesn't have must carry the number of the pull request or of an issue that it closes, and the log names it, such as 0182-the-new-way.md of pull request #1040 takes the number 1040, or that of an issue that it fixes, 1033. Where a record of main already has the number of the pull request, as in a young repository whose pull request #1 meets the template's 0001, the next number above the records of main takes its place, so that the pull request is never stuck. Without a pull request, such as on your machine, the step checks only that the numbers are unique. The step reads the description as the event of the run has it, so an edit of it counts from the next push.
  • Where the records of main come from: the first parent of the merge refs/pull/<n>/merge that the CI checks out. The checks of every kind of project check out with fetch-depth: 2, which holds it; a job that checks out another commit, or a clone without that parent, says so in its log and checks only that the numbers are unique. The description comes from the event of the run, so the step asks no API.
  • The index: a pull request leaves docs/decisions/README.md alone, and the step no longer asks for the row of a record that is not released. The release writes the rows with decisions --complete in the commit that writes CHANGELOG.md, and copies the status of each record into its row, so that a pull request that amends a record changes only the record. The website of MkDocs adds the missing rows while it builds, so its page lists every record at any time. decisions --fix fixes the rows that are wrong, as the fix bot does, and adds none.
  • The records up to 0181 keep their names, so that no link breaks: those of CHANGELOG.md and the release notes, the pages of the website and the citations in workflows, code and pages. The numbers jump from 0181 to the numbers of the pull requests and issues, which are past 1,000 in the blueprint. In each repository that follows the blueprint, the records end far below the numbers of its pull requests, so old and new numbers can't meet either.
  • A pull request writes at most one record of its own number; one that fixes several issues may write one for each.

Consequences

Two pull requests that each add a record merge without a conflict in docs/decisions/, and the branch bot updates either one; a record keeps its name from its first push. The numbers have gaps, and between two releases the index in the README on GitHub lacks the newest records, which the website shows. A build with Zensical runs no hooks of MkDocs (decision 0166), so it shows the index as the file has it, until a step of blueprint.py website completes the index before such a build. A pull request that adds a record and fixes no issue is opened first, as a draft if needed, and named after its number. An existing repository that follows the blueprint keeps its own docs/decisions/README.md, a file of the project, so its changelog entry says which sentence to change there (decision 0143).