Skip to content

changelog_md rule 2 rejects :rfc:NNNN#section-N, so citing an RFC section fails the gate even though the role is supported #592

Description

@JarryShaw

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:

  1. ``: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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions