Changelog entries are structured data

Changelog becomes an optional section whose entries are read as data: each entry is a list item beginning - , optionally dated YYYY-MM-DD: :, and holds the lines CommonMark gives that item, within a subset of list syntax where the tool's reading and CommonMark's agree. An undated entry still parses, with no date, and a new rule, L21, reports the missing date with an error while the document is editable and a warning once it is frozen. The export publishes the entries as structured data and leaves the section out of the document's contents.

The lines are read as written, before fenced code blocks and HTML comments are masked, so wrapped text, further paragraphs, a nested list, a code block and a link reference definition indented within the item all belong to the entry. A nested item is text within its entry, whatever it holds, so a date written in one is neither read nor checked. Its text is published as written, so it renders for a consumer as it does within the list item. The first line of an entry's text is what follows its date, so where that begins a block, such as # x, the text renders as that block though the list item renders it as a paragraph.

The section holds entries, blank lines and comment lines. Any other line belongs to no entry. Where L21 reports nothing in a sectionsection whose heading CommonMark reads as a heading at the top level of the document, its entries are the list items CommonMark reads there, each with the lines CommonMark gives it. A construct before the section that CommonMark reads as running over its heading, such as an HTML block, is outside what L21 checks. Where L21 reports a line, entries after it may be read differently from how they render, and are published as read.

L21 checks every Changelog section a document carries, whatever its type, as L20 checks every question sectionsections whatever the document's type. It does not check a withdrawn document, as L14 and L20 do not: a withdrawn document is abandoned, and withdraw performs no content checks, so a fault in one would stand once it is frozen.

accept and reject refuse a document with any fault L21 reports, as they refuse one L20 reports, for the same reason: under ADR-0001 a terminal document is never modified, and once it is terminal on the configured branch the fault could never be cleared. They apply every row of L21, except that the check against decided compares each entry's date with the decided date they are about to write rather than with the document's current one, so an entry dated after the day of the transition is refused. They make their checks that createdaccept also refuses a document whose closing section, Sources in a backfilled document, is not later than the day of the transitionfollowed by another level two heading, and which L08 reports with an error that a document being rejected does not end inside a comment or fencesoften: once Changelog and, before under RFC-0008, Open questions are not required, the gate, so each refuses by its own 's check a document L21 would also refuseof the required sections' order no longer places them before it. withdraw performs no content checks, unchanged.

The design rests on ADR-0001, whose freeze is why accept and reject refuse a document L21 reports; on ADR-0005, which admits no Markdown parser, so entries are read in a subset; on ADR-0006, whose provision for growth admits entries as a construct; on ADR-0009, which sets L21's severity on a frozen document, and so lets a frozen document's undated entries stand; on ADR-0019, under which the shape's break is the one schema: 3 already makes; and on ADR-0020, which takes the Changelog out of contents.

• A heading per entry. Each entry a heading carrying its date, with the text beneath, as questions are headings under RFC-0008. Lost because entries already written are list items in frozen documents, and could never be read or rewritten.
• An entry's later lines indented at least two spaces. Chosen first, with each continuation indented beneath its entry. Struck on 2026-10-14: an entry is a list item, which also runs over unindented lines.
• Everything up to the next entry line. Chosen on 2026-10-14, as an entry is a list item. Struck the same day: an entry is everything a Markdown parser takes as part of the list item, so a line the item does not continue, such as an unindented paragraph after a blank line, is not part of it.
• Reading every list item as CommonMark does. Each entry would be read with CommonMark's full list rules, so any list item renders as it is read. Lost Chosen on 2026-10-14 , with an entry holding everything CommonMark takes as part of the item, and rules written for the tool to follow. Struck the same day for the subset, because it needs CommonMark's block structure written by hand under ADR-0006, or a parser ADR-0005 does not admit, and every Changelog in this repository is within the subset. The rules first written for it read several shapes differently from how they render.
• Reporting a nested item shaped as a dated entry. It would catch an entry indented by mistake. Lost because a nested item is detail of one change, and a date in it is text, rendered nested as it is read.
• One line per entry. Offered on 2026-10-14 to remove the rules continuation lines needed. Lost because an entry is a list item, and a list item may run over several lines.
• A date required of every entry. An undated entry would not parse. Lost because a frozen document's entries can never gain a date, so its undated entries would never be published.
• Changelog as a required section, with its presence recorded in the export. Lost because the requirement guarantees only that an empty heading exists, as a document accepted the day it was proposed has no entries.
• Leaving out the check of dates against created and decided. Lost because the check catches a mistyped year.

The tool checks a Changelog today only for its presence and its order. Making it optional loosens both: an RFC without one, or with one out of order among the required sections, was reported by L08 and refused by the gate, and no longer is. A Changelog after Sources or Rejection rationale is still reportedreported by L08, and accept gains a refusal of any level two heading after Sources. The accept and reject gates gain the refusals described under Lifecycle.

In this repository, the only entries are the two every entry is dated, in RFC-0007order, both dated within its document's created and decided, and within the subset, so spec/ reports nothing. The tests do not hold:

• Three RFCs in testdata/repo, 0003-cache-expiry.md, 0004-database-component-on-postgresql.md and 0005-job-queues.md, carry an entry dated before their created, and that fixture is required to produce no errors, so their entries' dates are corrected.
• TestTheDocumentedWorkflowWorksEndToEnd fills the template's comments with prose, including the one in Changelog, and appends a line at the end of the file, inside Changelog. Neither belongs to an entry, so lint reports them the first where the test expects a clean run.
• The lint fixtures gain an L21 case, and the registered rule count rises by one more than RFC-0008's, to twenty-one.
• TestRequiredSectionsSurviveTheirAbsence expects at least seven RFC sections, and with RFC-0008 and this design there are five.
• The gate's test that a required section missing entirely is refused, even an ungated one, uses Changelog, which is no longer required.
• The export's schema is compared against its types, which gain changelog_entry.
• TestRejectRefusesADocumentWhoseParseStopsShortTestAcceptAllowsADecisionOnTheDayOfCreation and moves TestAcceptRefusesToWriteADecidedDateBeforeCreatedcreated build documents L21 also refuses, an entry opening a comment that never closes to the day of the transition and keeps an entry dated before created. The order under Lifecycle keeps each refused by it, which the check it testsgate refuses, so its entry's date is corrected.

• An undated entry, an entry with a date and no text, a line belonging to no entry, an entry out of order or outside the document's dates, an indented heading ending the section, and a second Changelog section are reported with an error while the document is editable, and with a warning once it is frozen. A second section was legal before.
• Lines belonging to no entry include a fence, a heading heading, a link reference or footnote definition, or a comment that does not close cleanly at column 0, a tab in a line's indentation, and a line at column 0 that CommonMark might not join to the entry above it.
• Entries written with *, +, a number or no marker are not read as entries. In a frozen document they are reported as a warning, and leave changelog and the default contents, appearing in source and under --all-headings.
• A Changelog heading, or the heading after the section, indented by two or three spaces, or read as a heading only once a comment is masked, is reported.
• A backfilled document with a level two heading after Sources is refused by accept.
• A withdrawn document is not checked.
• A heading differing from Changelog only in case, spacing or punctuation, once reported by L08 as a missing section, is reported by L21. Any other misspelling, such as Changlog, was reported by L08 and is now an ordinary section: nothing reports it, its entries are not read, and it is published in contents.
• A line beginning - outside a Changelog section is not read, and nothing about it changes.
• accept and reject refuse a document they previously moved, where L21 would report it.