Skip to content

The open-source template never tells a cycle that a behaviour change dates the documents it did not open #2776

Closed

Description

@argszero

The open-source contribution template tells a cycle to read the codebase, to obey the project's conventions, and — for a translated twin — to edit both copies in one change. It does not tell a cycle that a behaviour change dates the documents the change never opened, so the stale example, step, field list or stated limitation is left for a reviewer to find.

Where this shows up

The rule is general, not one project's habit. A change to a flag's name leaves the README's example output showing the old one; a change to an install path leaves a step in the install guide pointing where the file no longer is; a change to a protocol leaves a field list in the protocol document describing the previous message shape; a change that lifts a limitation leaves the sentence that named it standing, now false. Each of those is a document the diff never touched, and a reviewer who finds one cannot tell from the pull request whether the code or the document is wrong.

The template's §3.1.5 already owns "documents" as a subject twice — a claim written as the project's rule must name the message it rests on, and a document with a translated twin is edited in one change. Both are narrower instances. The missing piece is the general one: the material the change invalidates is found by searching, not by remembering.

What the fix must satisfy

  • The rule is stated in §3.1.5, where the subject already lives, in the template's own voice — not appended at the end of the file and not stated twice.
  • It names the search, because that is the part a cycle can act on: look for the old behaviour's own spelling — its name, its path, its count, its stated limitation — rather than relying on having noticed the document.
  • It says what a stale document is, so the finding is not a matter of taste: a defect the change introduced, not a follow-up for someone else.
  • It keeps the second half of the same idea, which is that a number written in prose is a number nothing keeps true: where a document states a count a guard can measure, the document states the guard.
  • No placeholder-rooted memory path, no language-policy sentence, and no git mutation is added — the template's existing guards pin those counts, and this change must not move them.

Activity

  1. argszero commented on Nov 9, 2026

    @argszero
    OwnerAuthor

    Handled by #2777

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

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions