docs: bring the README up to date, and release 0.6.1 - #20
Merged
Conversation
…se 0.6.1 The package description on PyPI had not been updated since 0.3.0. It listed none of the features added since: not NumPy becoming the only dependency, not save_npz/load_npz, not the training reports, and not the scikit-learn estimator interface that 0.6.0 exists to add. The 0.6.0 description does not contain the word "estimator" or "scikit-learn" anywhere. A PyPI description cannot be edited after upload, so correcting it takes a release. No code changed and results are identical to 0.6.0. The upgrade notes were also short of two things. 0.4.0 changes linear-initialization results for data far from the origin, where the previous PCA path was wrong by up to 5.8%, and it removed pandas and scikit-learn as runtime dependencies. Both now appear alongside the existing 0.3.0 warning, with a note that 0.5.0's string deprecation was withdrawn so anyone who saw the warning knows to stop migrating. Install now shows all three extras, and the quick start shows the estimator interface and save/load, since a reader comparing libraries reads the first code block and stops. Four feature bullets were bolded in a first draft and are not any more. Bolding four of fourteen items to draw the eye is emphasis as decoration, which the writing scan flags as bold-overuse; position does that job without shouting. Release verification gains a check that would have caught this before publishing rather than after: the built wheel's METADATA is grepped for the terms the release claims. twine check confirms the description renders, which says nothing about whether it is accurate.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A hotfix release. No code changed; results are identical to 0.6.0.
The problem
0.6.0's PyPI description does not contain the word "estimator" or "scikit-learn" anywhere. The release
whose headline feature is scikit-learn compatibility is the one release that never mentions it.
The README's feature list and upgrade notes had not moved since 0.3.0, so three releases were invisible
on the page most people read first:
save_npz/load_npz, no pickleTrainingReportprovenancefit/transform/predictand the[sklearn]adapterA PyPI description cannot be edited after upload. Publishing another version is the only mechanism
to change it, which is what makes this a release rather than a commit, and the semver justification:
the shipped metadata is wrong, and fixing shipped metadata is a patch.
The gap that mattered more than the feature list
Upgrading stopped at 0.3.0. It warned that
random_seedno longer reproduces pre-0.3.0 maps, and saidnothing about 0.4.0 changing linear-initialization results for data far from the origin, where the
old PCA path was wrong by up to 5.8%. For a library backing a thesis, a silent numerical change is the
single most important thing an upgrade note can carry.
Now covered, along with 0.4.0 dropping pandas and scikit-learn as runtime dependencies, and a line
saying 0.5.0's string deprecation was withdrawn so anyone who saw that warning knows to stop migrating.
Also
cliwas listed.fit/predictandsave_npz, since a reader comparinglibraries reads the first code block and stops.
banditandpip-audit.docs/index.mdis a one-line include of the README, so the docs site picks all of this up with nosecond edit.
Writing scan
Run before opening this, per the plan. Zero severity-5 findings. Two things it caught in my own
draft:
bold-overuse. I had bolded four of fourteen feature bullets to draw the eye to the new ones,which is emphasis as decoration and the same habit the scan caught in the changelog earlier. Removed;
position does that job without shouting.
rule-of-threehits, all checked individually and all genuine enumerations that stay: thearray-like types accepted, the three initialization modes, the three neighborhood functions, the
report's fields, and the real data examples.
The check that would have caught this earlier
twine checkconfirms a description renders. It says nothing about whether it is accurate. Sorelease verification now greps the built wheel's own
METADATA:Verification
424 tests unchanged at 100% coverage, ruff /
ruff format/mypy --strictclean,mkdocs build --strictexits 0 (which is what proves the index include still resolves),twine checkpasses bothartifacts.
After merge
Tag
v0.6.1; the workflow builds and waits at thepypigate for you to authorise.