Release v0.7.0

TopMark v0.7.0 — Release Notes

🎉 This release ships a refreshed version command, a hardened release pipeline, and stricter docs quality gates. It also finalizes the CI/release split introduced in the RCs.

🚀 Highlights

• Version CLI overhaul

  • topmark version now defaults to PEP 440 output.
  • New --format {pep440,semver,json,markdown} (and shortcut --semver) lets you pick your preferred representation.
  • Shared converter: topmark.utils.version.pep440_to_semver().

• Release hardening

  • GitHub Actions release flow now enforces strict gates:
    • Version/tag match (pyproject.toml ↔ tag)
    • Docs must build with mkdocs --strict
    • Artifacts verified (sdist/wheel exist and embed the expected version)
    • Pre-releases go to TestPyPI, finals to PyPI
    • Final releases are checked to be newer than the latest final on PyPI
  • Trusted Publishing (OIDC) for TestPyPI/PyPI.

✨ Added

• CLI – version command
  • --semver and --format json|markdown|pep440|semver.
  • Stable JSON schema:

    {"version": "<str>", "format": "pep440|semver"}

• Tests
  • Parameterized coverage for text/JSON/Markdown + SemVer vs PEP 440.

🔧 Changed

• CLI output

  • Markdown now shows the format label:

    **TopMark version (pep440|semver): <version>**
    

  • Plain text remains just the version (script-friendly).

• CI / Release

  • CI runs on PRs, main, and v* tags; release workflow is triggered on tag push or post-CI.
  • New details job derives normalized versions (PEP 440 & SemVer), channel (TestPyPI vs PyPI), and prerelease flag.
  • Concurrency guard prevents duplicate publishes.

📚 Docs

• New/updated workflow docs:
  • docs/ci/release-workflow.md (RC vs final, gates, publishing).
  • CONTRIBUTING.md (CI expectations, local checks).
• README.md and site examples updated for the new version outputs.

🧪 Tooling & Reproducibility

• Adopt pinned lockfiles: requirements.txt, requirements-dev.txt, requirements-docs.txt + constraints.txt.
• Consistent python -m pip; caches keyed on lockfiles.

🗑️ Removed

• Duplicate “Build docs (strict)” step in CI lint job.
• Stray topmark.toml at repo root.

⚠️ Breaking (pre-1.0)

• JSON schema changed from:

  {"topmark_version": "<str>"}

  to:

  {"version": "<str>", "format": "pep440|semver"}

• Markdown output for version now explicitly includes the format label:

  **TopMark version (pep440|semver): <version>**
  

  If you parse topmark version output, update your consumers accordingly.

🔁 Pre-releases

• 0.7.0-rc1 and 0.7.0-rc2 were published to TestPyPI and are fully subsumed by this GA.

📦 Installing / Upgrading

pip install -U topmark
# or with optional extras (examples)
pip install -U "topmark[dev]"    # development toolchain
pip install -U "topmark[docs]"   # docs toolchain

---

Links

• PyPI: https://pypi.org/project/topmark/
• Docs: https://shutterfreak.github.io/topmark/
• Changelog: see CHANGELOG.md in the repo
• Full Changelog: v0.6.2...v0.7.0