Skip to content

Check the claims the docs make, since three open issues are all documentation drift #54

Description

@arnelirobles

Band: small

Three of the open issues in this milestone are the same failure: the code changed and the prose did not. Rather than correcting each one and waiting for the next, check them.

What has drifted, as of v2.8.0:

  • README.md:111 says 525 tests. The suite is 601 across nine projects.
  • The coverage badge links to docs/test_coverage_report.md. The file is at docs/internal/test_coverage_report.md, so the badge is a dead link.
  • docs/README.md links eight package guides under docs/packages/. That directory does not exist.
  • The 2.7.0 changelog says AddVerdictProblemDetails scopes configuration to the container. The two interfaces it registers have no call site anywhere in src/.

What should change

One test project, or one test in an existing one, asserting the things a human keeps getting wrong:

  • The test count in README.md matches what the suite actually reports. Easiest as a source-generated constant or a file the test run writes and the test reads, rather than parsing prose.
  • Every relative link in README.md, docs/README.md and CONTRIBUTING.md resolves to a file that exists. This is a dozen lines with Regex over the markdown and File.Exists, and it catches two of the four above on its own.
  • The badge targets resolve, same check.

The changelog one does not generalise into a test and should not be forced into one. The interface-has-a-call-site check belongs in the API approval test, which already exists and already has the right shape for it.

Unglamorous, and it retires three issues at once and stops them recurring.

Activity

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

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions