fix(sdk-extras): exclude pre-releases, so the gate checks the version readers get

[LukasWodka]

Bugbot Medium on the staging promotion PR #114.

The bug

parse_version reduces a tag to a tuple of leading digits, so 0.19.0a1 becomes (0, 19, 0) and outranks 0.18.1 at (0, 18, 1). resolve_version then answers "which version does this documented specifier select?" with a pre-release — and pip does not install those without --pre, which none of the documented pip install "tracebloc[...]" commands pass.

The gate would check the extras of a version no reader can obtain. Wrong in both directions: a missing extra in a stable release goes unnoticed, and an extra that exists only in an alpha reads as present.

Latent today — all 11 published releases are stable. It arms itself the day an alpha is published.

Why hand-rolled and not packaging

sdk-extras-check.yml runs python3 scripts/check-sdk-extras.py with no setup-python and no pip install — the script is stdlib-only by construction, so packaging.version is not importable and reaching for it would mean adding a dependency step to a docs check.

.postN is deliberately excluded from the marker set: post releases install by default.

One limit, stated rather than hidden

If a package had only pre-releases, the fallback picks an arbitrary one — parse_version reduces 1.0.0a1 and 1.0.0b2 to the same tuple, and ordering them needs real PEP 440 parsing. That branch is a guard against an empty max(), not a path anyone rides.

Verified

• 10 classification cases: a/b/rc/alpha/preview/dev → pre-release; post/plain → not
• the reported bug both ways: with the filter 0.18.1, without it 0.19.0a1
• the real gate still runs clean against live PyPI: "Checked 10 documented specs; all documented extras exist in the versions they resolve to."

---

Note

Low Risk
Docs CI tooling only; behavior change is narrowing version selection to stable releases with a documented fallback when no stable tags exist.

Overview
Fixes version resolution in the SDK extras docs gate so it matches what pip installs without --pre.

resolve_version used parse_version, which strips alpha/beta/rc suffixes—so a tag like 0.19.0a1 could rank above 0.18.1 and the check would validate extras on a release readers cannot install.

The change adds stdlib-only is_prerelease (regex aligned with common PEP 440 markers; .post stays eligible) and filters pre-releases out of the candidate list before max(), with a fallback to the full list only if every release is a pre-release. The resolve_version docstring documents that edge case.

^{Reviewed by Cursor Bugbot for commit aa60576. Bugbot is set up for automated code reviews on this repo. Configure here.}