Rule 2 converts only the bare-number form of Sphinx's :rfc: role, so an entry citing a section anchor fails the Changelog drift gate with no way to tell from the message that the role itself is supported.
Mechanism
util/changelog_md.py:314:
line = re.sub(r':rfc:`(\d+)`', lambda match: f'[RFC {match[1]}]({RFC_URL}{match[1]})', line)
(\d+) anchored between the backticks accepts digits and nothing else. Sphinx's :rfc: role also accepts an anchor — ``:rfc:6554#section-3``` — which is the form anyone writing prose about a specific section naturally reaches for, and the docstring at util/changelog_md.py:43` advertises the role as supported without saying which spelling:
- ``:rfc:`NNNN``` becomes a Markdown link to the RFC on the IETF datatracker;
So the anchor form falls straight through to residual() and the entry is rejected as using "reStructuredText the six conversion rules do not cover" — when in fact rule 2 exists precisely for that role.
Measured
On #590's head a25ccff59, whose entry contains ``:rfc:`6554#section-3```:
line 46: an unconverted interpreted-text role: ':rfc:`...`'
line 46: an unconverted interpreted-text role: ':rfc:`...`'
Two hits from that one construct, and the gate fails. Rewriting as ``:rfc:`6554``` with the section in prose passes.
Why it is worth fixing rather than documenting
Two of the four pull requests opened against this repo today tripped this gate, #586 and #590, and neither author could see from the error which of the six rules was meant to cover what they wrote. The failure is a merge blocker whose message actively misleads:
Suggested fix
Widen the pattern to accept the anchor and carry it into the link target, e.g. :rfc:(\d+)(#[\w-]+)?`` producing [RFC 6554 section 3](…/rfc6554#section-3). The datatracker URL already accepts the fragment, so the emitted link works.
If the anchor form is deliberately unsupported instead, then the docstring at util/changelog_md.py:43 and the error message should both say so explicitly, because the current pair tells an author that the role is fine and that their usage is not.
Found while running down #590's gate failure. Related: #588, the line-number defect in the same error path.
Rule 2 converts only the bare-number form of Sphinx's
:rfc:role, so an entry citing a section anchor fails theChangelog driftgate with no way to tell from the message that the role itself is supported.Mechanism
util/changelog_md.py:314:(\d+)anchored between the backticks accepts digits and nothing else. Sphinx's:rfc:role also accepts an anchor — ``:rfc:6554#section-3``` — which is the form anyone writing prose about a specific section naturally reaches for, and the docstring atutil/changelog_md.py:43` advertises the role as supported without saying which spelling:So the anchor form falls straight through to
residual()and the entry is rejected as using "reStructuredText the six conversion rules do not cover" — when in fact rule 2 exists precisely for that role.Measured
On #590's head
a25ccff59, whose entry contains ``:rfc:`6554#section-3```:Two hits from that one construct, and the gate fails. Rewriting as ``:rfc:`6554``` with the section in prose passes.
Why it is worth fixing rather than documenting
Two of the four pull requests opened against this repo today tripped this gate, #586 and #590, and neither author could see from the error which of the six rules was meant to cover what they wrote. The failure is a merge blocker whose message actively misleads:
.rstbut are counted against the converted body (ResidualMarkupError cites the source .rst but numbers lines against the converted body, so the line number is always wrong #588);##[error]annotation adds "The unified diff above shows what moved" when no diff was ever produced, becauserender()raised before comparing.Suggested fix
Widen the pattern to accept the anchor and carry it into the link target, e.g.
:rfc:(\d+)(#[\w-]+)?`` producing[RFC 6554 section 3](…/rfc6554#section-3). The datatracker URL already accepts the fragment, so the emitted link works.If the anchor form is deliberately unsupported instead, then the docstring at
util/changelog_md.py:43and the error message should both say so explicitly, because the current pair tells an author that the role is fine and that their usage is not.Found while running down #590's gate failure. Related: #588, the line-number defect in the same error path.