From 2470f06d057dd3a1548c7f9d2480c547d8be8979 Mon Sep 17 00:00:00 2001 From: melbinjp Date: Mon, 31 Aug 2026 13:36:00 +0530 Subject: [PATCH] 0.2.4, because the README said it was not on PyPI while it was docproof went up on PyPI on 24 August. The README kept saying "Not on PyPI yet" and, further down, "docproof is not on PyPI, so there was nothing for pipx to resolve". Since the README is the package long_description, that false claim has been sitting on the PyPI page describing the package to the people installing it. RELEASING.md already required exactly this: "Two parts of README.md are written for a package that is not yet on PyPI: the install instructions and the note saying so. Both must change in the commit that ships." That was written, and then 0.2.1, 0.2.2 and 0.2.3 all shipped without doing it. The instruction has been rewritten to say what actually happened, because an instruction that did not work is not a fix. Install section now leads with `pip install docproof` and keeps the checkout path for people changing the tool. The placeholder sample header moves to 0.2.4; the verbatim pallets/click transcript at the top is untouched, per the test that deliberately excludes it. --- README.md | 28 +++++++++++++++------------- RELEASING.md | 10 +++++++--- src/docproof/__init__.py | 2 +- 3 files changed, 23 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 725f4b5..29582eb 100644 --- a/README.md +++ b/README.md @@ -345,11 +345,8 @@ before writing the rule, and let the disagreements decide what the rule has to a ## Install and run -**Not on PyPI yet.** From a checkout: - ```bash -git clone https://github.com/melbinjp/docproof && cd docproof -pip install -e . +pip install docproof docproof # check the project you are standing in docproof path/to/project @@ -357,9 +354,12 @@ docproof --show-skips # and everything it declined to judge, with reasons docproof --list # the available checks ``` -The `pip install docproof` line goes in when there is something on PyPI to install. A -tool whose whole argument is that documentation should be checkable does not get to open -with an instruction that does not work. +From a checkout instead, which is what you want if you are changing it: + +```bash +git clone https://github.com/melbinjp/docproof && cd docproof +pip install -e . +``` To run the suite, which is the thing worth checking before trusting any of the above: @@ -434,7 +434,7 @@ not a promise the project is making. silence harmless: ``` -docproof 0.2.3 - myproject, 6 document(s) +docproof 0.2.4 - 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"] @@ -519,11 +519,13 @@ cloned at `--depth 1` reports "Nothing contradicted" and exits **0**. Since check would hand you a permanently green gate that had judged nothing. It fails with the one-line fix in the message instead. CI here runs that refusal as a test. -*This block used to read `pipx run docproof`, which never worked: docproof is not on PyPI, -so there was nothing for pipx to resolve. It sat here for weeks because nothing was checking -that the install instructions ran, which is precisely the defect this tool exists to find. -The `self` job now installs through the action above, so the snippet cannot rot again -without the build going red.* +*Both halves of this were wrong once. This block read `pipx run docproof`, and the install +section above opened by saying the package was not published yet, and neither survived +docproof actually going up on PyPI on 24 August 2026. A tool whose whole argument is that +documentation should be checkable does not get to ship an install instruction that does not +work. The `self` job installs through the action above so the snippet cannot rot again +without the build going red, and `RELEASING.md` names both places as things the shipping +commit has to change.* There are no dependencies at all on Python 3.11+; on 3.10 it installs `tomli` to read `pyproject.toml`. diff --git a/RELEASING.md b/RELEASING.md index f290c84..e4bfc92 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -68,9 +68,13 @@ reused. A mistake in 0.1.0 is corrected by releasing 0.1.1, never by replacing 0 Deleting the project does not release the name for a fresh start either. This is why the trigger is a tag rather than a push to `main`, and why the environment gate exists. -Two parts of `README.md` are written for a package that is not yet on PyPI: the install -instructions and the note saying so. **Both must change in the commit that ships** — a tool -that checks documentation against reality should not fail its own check on release day. +Two parts of `README.md` used to be written for a package that was not yet on PyPI: the +install instructions and the note saying so. **Both were supposed to change in the commit +that shipped, and did not.** 0.2.1, 0.2.2 and 0.2.3 all went up while the README still said +"Not on PyPI yet", so the package page carried a false claim about itself for a week. Fixed +in 0.2.4. The rule stands and is worth restating: a tool that checks documentation against +reality should not fail its own check on release day, and this instruction being here was +not enough to make it happen. ## What the version number claims diff --git a/src/docproof/__init__.py b/src/docproof/__init__.py index c7fa0d4..240408b 100644 --- a/src/docproof/__init__.py +++ b/src/docproof/__init__.py @@ -1,3 +1,3 @@ """docproof - prove your documentation against your code.""" -__version__ = "0.2.3" +__version__ = "0.2.4"