Skip to content

docs(ci): line anchors generated or pinned by tooling, against the anchor-by-name rule #2165

Closed

Description

@JarryShaw

What: three tools produce or require file:line anchors, which the anchor-by-name rule forbids.

  1. util/update_python_versions.py. COMPAT_ROW, rewrite_compat_rows and two python-versions.toml:(\d+)-(\d+) claims write .github/python-versions.toml:N into workflows.rst. test_the_workflows_page_cites_each_version_on_its_line in tests/project/test_python_versions_1660.py pins that form. Cite the "3.11" = … keys instead.

  2. The recorded-defect contract. It asks for "the file:line that causes it" in:

    • test_option_roundtrip_unit.py (the defect field and its failure message);
    • tests/{corekit,foundation}/_roundtrip.py and tests/protocols/_edge_roundtrip.py;
    • test_dispatch_registry_unit.py's message;
    • test-coverage.rst.

    No current entry uses one, so only the contract needs to change.

  3. test_resource_monitor_1740.TestTheDocsSayIt. It pins src/Runner.Worker/StepsRunner.cs:205-208 in workflows.rst. That range is the shutdown check in StepsRunner.RunAsync at actions/runner 796cc18ff. Its sibling :322-353 was renamed to StepsRunner.RunStepAsync in round 5 (docs(tests): fifth whole-repo pass over tests (#1103) #2159, docs(docs): fifth whole-repo pass over the non-API docs, with issue/PR roles (#1103) #2161).

Needs a ruling (my recommendation in brackets):

  • Part 1: these anchors are regenerated and test-checked, so they can't drift, which is the rule's stated reason. [Cite by name anyway: a reader can't follow :19 without opening the file.]
  • Part 3: is it the same question as docs: #719-style prose sweep after the #1090–#1102 defect wave #1103's ruling 4, on third-party citations pinned to a commit? [Yes, so it follows that ruling.]

Part 2 is a plain fix.

Activity

  1. added
    docsPull requests that change documentation only (docs: subject prefix)
    testPull requests that add or correct tests (test: subject prefix)
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Oct 25, 2026
  2. moved this to Needs decision in PyPCAPKiton Oct 25, 2026
  3. JarryShaw commented on Oct 25, 2026

    @JarryShaw
    OwnerAuthor

    Take recommendations

  4. JarryShaw commented on Oct 25, 2026

    @JarryShaw
    OwnerAuthor

    Recorded: the recommendations stand.

    • Part 1: cite by name even where tooling regenerates and checks the anchor. The updater writes the "3.11" = … key rather than python-versions.toml:N, and the test changes to match.
    • Part 2: the recorded-defect contract asks for a name, not a file:line.
    • Part 3 follows docs: #719-style prose sweep after the #1090–#1102 defect wave #1103's ruling 4, which is still open, so it waits on that ruling.

    A worker is starting on parts 1 and 2 now.

  5. added
    wipWork in flight - a covering PR is open or an agent is actively on it
    and removed
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Oct 25, 2026
  6. moved this from Needs decision to WIP in PyPCAPKiton Oct 25, 2026
  7. removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Oct 25, 2026
  8. added this to the PyPCAPKit v1.5 milestone on Oct 26, 2026
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

    docsPull requests that change documentation only (docs: subject prefix)testPull requests that add or correct tests (test: subject prefix)

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions