Skip to content

Finish bitmath 2.1.0 NEWS.rst and tidy Sphinx config#148

Merged
timlnx merged 6 commits into
masterfrom
2.1.0-cleanup-tasks
May 25, 2026
Merged

Finish bitmath 2.1.0 NEWS.rst and tidy Sphinx config#148
timlnx merged 6 commits into
masterfrom
2.1.0-cleanup-tasks

Conversation

@timlnx
Copy link
Copy Markdown
Owner

@timlnx timlnx commented May 24, 2026 •
edited
Loading

Summary

Two focused changes for the bitmath 2.1.0 release happening today.

  • NEWS.rst: fills out the bitmath-2.1.0 section. Flips *Unreleased* to *Released: May 24, 2026*, expands the intro to name the supply-chain work, adds a Hypothesis property-testing bullet under Project Infrastructure, and adds two new sections:

    • Security and Supply Chain: OpenSSF Best Practices passing badge, OSPS Baseline L1/L2/L3 status (with single-maintainer caveat on OSPS-QA-07.01), OSSF Scorecard 7.8, SHA-pinned GitHub Actions, Dependabot, hardened workflow token permissions, pip-audit SCA, CycloneDX SBOM attached to releases.
    • Project Documentation and Governance: linked filename headers for MAINTAINERS.md, ARCHITECTURE.md, SECURITY_ASSESSMENT.md, SECURITY_POLICIES.md, VERIFICATION.md, plus the SECURITY.md CVD response timeframes and the https-everywhere doc-URL sweep.

  • docsite/source/conf.py: switches source_suffix from the string form ('.rst') to the dict form ({'.rst': 'restructuredtext'}) so Sphinx stops logging the auto-conversion notice on every make docs run.

Test plan

  • make docs builds cleanly with zero warnings
  • No em-dashes in any new prose
  • All filename links in the new Documentation section resolve to files that exist on master
  • 2.0.0 and 1.x section anchors in NEWS.rst preserved untouched
  • Reviewer eyeball pass on the new release-notes copy

timlnx added 2 commits May 24, 2026 16:59
@timlnx
Write bitmath-2.1.0 release notes in NEWS.rst
c1db3a4 
Flips Unreleased to Released (2026-05-24), expands the intro to
mention the supply-chain work, adds a Hypothesis property-testing
bullet under Project Infrastructure, and adds two new sections:

- Security and Supply Chain: OpenSSF Best Practices badge, OSPS
  Baseline L1/L2/L3 status, OSSF Scorecard, SHA-pinned actions,
  Dependabot, hardened workflow token permissions, pip-audit SCA,
  CycloneDX SBOM attached to releases.

- Project Documentation and Governance: MAINTAINERS.md,
  ARCHITECTURE.md, SECURITY_ASSESSMENT.md, SECURITY_POLICIES.md,
  VERIFICATION.md, SECURITY.md CVD response timeframes, and the
  https-everywhere doc-URL sweep. Each filename header links to the
  file on master.
@timlnx
Use dict form for source_suffix in Sphinx config
3a3564a 
Sphinx now auto-converts the string form ('.rst') to the dict form
({'.rst': 'restructuredtext'}) at build time and logs a notice every
run. Declaring the dict form directly keeps make docs output quiet
and matches current Sphinx documentation.
@timlnx timlnx added the docs label May 24, 2026
@timlnx timlnx self-assigned this May 24, 2026
timlnx added 4 commits May 24, 2026 18:01
@timlnx
Fix broken and insecure URLs across docsite and NEWS
ecb2bbd 
Sweep of dead and http-scheme links surfaced by a curl-based audit
of all URLs in the docsite and NEWS.rst.

Broken (4xx) replaced with working targets:

- classes.rst: BIPM SI brochure chapter3 path is gone; point at the
  brochure landing page.
- real_life_examples.rst: Apple's 2001 iPod press release is gone;
  point at a Wayback Machine snapshot so the citation survives.
- NEWS.rst: Fedora admin.fedoraproject.org pkgdb is long deprecated;
  point at src.fedoraproject.org/rpms/python-bitmath.

http -> https upgrades on working hosts:

- appendices/on_units.rst: tldp.org
- appendices/who_uses.rst: travelcrm.org.ua
- simple_examples.rst: miniwebtool.com (canonical drops www)

NEWS.rst revert: the Coveralls account never moved with the GitHub
rename, so the badge URL must stay at coveralls.io/github/tbielawa,
not timlnx. Earlier sweep was over-aggressive.
@timlnx
Refresh canonical URLs across docsite and NEWS
376521e 
Round two of the URL audit: items that currently auto-redirect but
where the canonical target has moved.

GitHub account rename (tbielawa -> timlnx):

- index.rst.in: link to the tests/ directory.
- NEWS.rst: historical PR links for #105 and #107.

Note: NEWS.rst:870 Coveralls badge stays at tbielawa on purpose. The
Coveralls account did not migrate with the GitHub rename and that URL
is where the coverage data actually lives.

Fedora wiki -> docs.fedoraproject.org/en-US/epel/:

- NEWS.rst (two occurrences) for the EPEL reference.

pypi.python.org -> pypi.org:

- NEWS.rst: bitmath project page.
- index.rst.in: hurry.filesize reference for prefix-selection prior art.

mkaz.blog Python String Format Cookbook moved to a new path under the
working-with-python tree:

- instances.rst seealso link.

TravelCRM (appendices/who_uses.rst): Bitbucket source repo is gone
(Bitbucket dropped Mercurial in 2020) and the project itself appears
abandoned. Removed both links and the dangling Bitbucket clause;
kept the bare-text mention as a historical entry.
@timlnx
Wire up Sphinx linkcheck via make linkcheck
95b6423 
Adds a `make linkcheck` target that dispatches to Sphinx's built-in
linkcheck builder. Scans every external URL in the docsite plus
NEWS.rst (included via `.. include::`) and writes a structured report
to docsite/build/linkcheck/output.txt.

Configured in docsite/source/conf.py:

- 8 parallel workers (default is 5)
- 15-second timeout per URL
- 2 retries on transient failures
- Anchor checking enabled (catches dead #L<n> line refs etc.)
- Ignore patterns for known-quirky endpoints:
  - api.securityscorecards.dev (serves SVG, 405 on HEAD, 302 on GET)
  - web.archive.org pinned snapshots (occasional 5xx during indexing)

Not wired into `make ci` on purpose. Link rot happens independently
of code changes, so the right home for this is a weekly GH Actions
cron, not every PR build. To run locally: `make linkcheck`.
@timlnx
Apply linkcheck findings: kill redirects, drop stale anchors
65d86c5 
Round three of the URL audit, this time driven by `make linkcheck`
output rather than manual curling. linkcheck caught several things
the earlier passes missed.

Stale anchors dropped:

- NEWS.rst: Makefile#L177 link from a 2014 entry; the virtualenv:
  target sits at L186 now and pinning by line number to a 10+ year
  old file location is fragile. Drop the anchor; keep the file link.

URL refreshes that were currently 30x-redirecting:

- NEWS.rst: pypi-attestations repo moved from trailofbits to the
  pypi org (this URL came in with my 2.1.0 NEWS write-up).
- on_units.rst: tldp.org dropped the www subdomain canonically.
- who_uses.rst: codedellemc -> thecodeteam for the ScaleIO flocker
  driver.
- related_projects.rst: pypi.python.org -> pypi.org for the
  hurry.filesize prior art reference (last pypi.python.org URL in
  the tree).

readthedocs trailing-path normalization (so the URL stops bouncing
through a redirect to its own /en/{latest,stable}/ canonical):

- contributing.rst: pytest-cov, pylint
- integration_examples.rst, module.rst: progressbar2

Badge host: readthedocs.org/projects/bitmath/badge -> the new
app.readthedocs.org host the project redirects to.

docsite/source/conf.py: cap linkcheck_rate_limit_timeout at 10s so
a single rate-limited host (GitHub, gnu.org) does not stall an
interactive `make linkcheck` run for minutes at a time. Default is
60+ seconds because Sphinx honors Retry-After headers; 10s is more
useful for local iteration.
@timlnx timlnx merged commit cf0c16d into master May 25, 2026
39 checks passed
@timlnx timlnx deleted the 2.1.0-cleanup-tasks branch May 25, 2026 04:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@timlnx timlnx

Labels

docs

Projects

None yet

Milestone

2.1.0 - End of breaking changes

Development

Successfully merging this pull request may close these issues.

1 participant

@timlnx