From 4c3af590e793e76417ab41bde47725757afb4f21 Mon Sep 17 00:00:00 2001 From: melbinjp Date: Wed, 19 Aug 2026 10:26:14 +0530 Subject: [PATCH] 0.2.0: coverage reporting, and two fixes to what a finding says Six commits have landed since v0.1.4 and the package still called itself 0.1.4, so anyone following the README's own install instructions - clone main, pip install -e . - got a tool reporting a version it was not. #16 say how many documents were NOT read, and where they are #17 report the line a path is on, not the line its fence started on #18 read a directory diagram whose entries carry a description column #19 the release gate, dead since v0.1.3 0.2.0 rather than 0.1.5 because #16 adds output to every run. Three README action pins move with it, which release.yml requires and now actually enforces. AND THE SAMPLE REPORT HEADER, WHICH NOTHING WATCHED. The README prints an illustrative run whose header carries the version; it read 0.1.4 while the package moved on. Same drift the action pins have a gate for, in the same file, unguarded. There is a test now. That test failed on its first run, and it was right to. The README also opens with a VERBATIM run against pallets/click whose header says docproof 0.1.0, and that one must never be updated: the tool misreported its own version until #9, the block is a real transcript, and the README argues at length that editing it "would make it a mock-up: the same move as editing a document instead of fixing the code". A check that would force a true record to be falsified is worse than no check, so the test reads only headers naming the placeholder project. A transcript names a real repository; a sample names myproject. 193 tests. ruff, format and mypy clean. Simulated the release gate locally against this tree: tag v0.2.0 passes both the version check and the README-pin check. --- README.md | 8 +++---- src/docproof/__init__.py | 2 +- tests/test_version_has_one_source.py | 31 ++++++++++++++++++++++++++++ 3 files changed, 36 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0738ab2..c76e129 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ clean bill of health nobody examined is worth less than nothing. - uses: actions/checkout@v4 with: fetch-depth: 0 # docproof needs history to tell drift from an example -- uses: melbinjp/docproof@v0.1.4 +- uses: melbinjp/docproof@v0.2.0 ``` **Both lines are load-bearing, and the action refuses to run without the first.** @@ -345,7 +345,7 @@ A gate that fails on day one gets removed on day one. `--exit-zero` prints the f leaves the run green, so you can adopt this while you are still working through them: ```yaml -- uses: melbinjp/docproof@v0.1.4 +- uses: melbinjp/docproof@v0.2.0 with: fail-on-findings: false ``` @@ -398,7 +398,7 @@ not a promise the project is making. silence harmless: ``` -docproof 0.1.4 - myproject, 6 document(s) +docproof 0.2.0 - myproject, 6 document(s) 41 documentation file(s) elsewhere in the tree were NOT read; the default scope is top-level files plus doc/ and docs/ guides/ 22, website/ 14, handbook/ 4, .github/ 1 read them too with --docs 'guides/**/*.md' or [tool.docproof] docs = ["guides/**/*.md"] @@ -473,7 +473,7 @@ never existed, so `docproof` reports that and judges nothing rather than guessin - uses: actions/checkout@v4 with: fetch-depth: 0 # docproof needs history to tell drift from an example -- uses: melbinjp/docproof@v0.1.4 +- uses: melbinjp/docproof@v0.2.0 ``` **The action refuses to run without `fetch-depth: 0`, on purpose.** Measured on diff --git a/src/docproof/__init__.py b/src/docproof/__init__.py index 7417332..647885a 100644 --- a/src/docproof/__init__.py +++ b/src/docproof/__init__.py @@ -1,3 +1,3 @@ """docproof — prove your documentation against your code.""" -__version__ = "0.1.4" +__version__ = "0.2.0" diff --git a/tests/test_version_has_one_source.py b/tests/test_version_has_one_source.py index a44688c..fd66184 100644 --- a/tests/test_version_has_one_source.py +++ b/tests/test_version_has_one_source.py @@ -124,3 +124,34 @@ def test_the_release_gate_reads_the_same_file_the_build_does() -> None: "release.yml no longer resolves the version file through [tool.hatch.version]. " "Hardcoding it lets the gate and the build drift onto different files." ) + + +def test_the_readme_sample_report_shows_the_current_version() -> None: + """The README's ILLUSTRATIVE sample report carries a version, and it went stale. + + It read `docproof 0.1.4` while the package moved on: the same drift the action pins + already have a gate for, in the same file, unguarded. + + **Placeholder samples only, and the exclusion is the interesting half.** The README also + opens with a verbatim run against `pallets/click` whose header says `docproof 0.1.0`, and + that one must NOT be updated. The README says why, at length: the tool misreported its own + version until #9, the block is a real transcript, and *"editing the output would make it a + mock-up: the same move as editing a document instead of fixing the code."* + + The first version of this test asserted every header matched and failed on exactly that + block - correctly, and with the wrong remedy. A check that would force a true record to be + falsified is worse than no check, so this reads only headers naming the placeholder + project. A transcript names a real repository; a sample names `myproject`. + """ + from docproof import __version__ + + readme = (ROOT / "README.md").read_text(encoding="utf-8") + samples = re.findall(r"^docproof (\d+\.\d+\.\d+) . myproject", readme, re.M) + + assert samples, "the README shows no placeholder sample report header to check" + wrong = sorted({s for s in samples if s != __version__}) + assert wrong == [], ( + f"README sample report shows {wrong} but the package is {__version__}. " + "A tool whose argument is that documentation drifts does not get to print a " + "version it is not." + )