Skip to content

docs: bring the README up to date, and release 0.6.1 - #20

Merged
andremsouza merged 1 commit into
masterfrom
docs/readme-catches-up
Jul 30, 2026
Merged

docs: bring the README up to date, and release 0.6.1#20
andremsouza merged 1 commit into
masterfrom
docs/readme-catches-up

Conversation

@andremsouza

Copy link
Copy Markdown
Owner

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:

missing from the README added in
NumPy is the only dependency, 333 MB → 69 MB 0.4.0
save_npz / load_npz, no pickle 0.4.0
TrainingReport provenance 0.4.0
options checked by a type checker 0.4.0
fit/transform/predict and the [sklearn] adapter 0.6.0

A 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_seed no longer reproduces pre-0.3.0 maps, and said
nothing 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

  • Install shows all three extras; only cli was listed.
  • The quick start gains a second block showing fit/predict and save_npz, since a reader comparing
    libraries reads the first code block and stops.
  • Development mentions bandit and pip-audit.
  • docs/index.md is a one-line include of the README, so the docs site picks all of this up with no
    second 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.
  • Six rule-of-three hits, all checked individually and all genuine enumerations that stay: the
    array-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 check confirms a description renders. It says nothing about whether it is accurate. So
release verification now greps the built wheel's own METADATA:

wheel: python_som-0.6.1-py3-none-any.whl   Version: 0.6.1
  yes  'estimator'          yes  'scikit-learn'      yes  'save_npz'
  yes  'GridSearchCV'       yes  'python-som[sklearn]'
  yes  'NumPy is the only runtime dependency'

Verification

424 tests unchanged at 100% coverage, ruff / ruff format / mypy --strict clean, mkdocs build --strict exits 0 (which is what proves the index include still resolves), twine check passes both
artifacts.

After merge

Tag v0.6.1; the workflow builds and waits at the pypi gate for you to authorise.

…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.
@andremsouza
andremsouza merged commit cdba19d into master Jul 30, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant