Release and compatibility policy

Hamen Markup 1.0.0 is the first stable release of the documented compiler and local notes workflow. Supported syntax and deliberately bounded rendering behavior are described by the notes guide, strict syntax reference, component schemas, and implementation contracts.

Compatibility

• Patch releases fix defects and improve diagnostics without intentionally breaking documented valid source.
• Minor releases add backward-compatible syntax or components.
• Major releases may change source contracts and will document migration steps.
• Earlier @MarkupVersion("0.1.0"), "0.2.0", and "0.2.1" declarations remain accepted by 1.0.0. They do not emulate historical renderer defects. New explicit declarations should use @MarkupVersion("1.0.0").
• Notes use .hmn, @Notes(), or explicit Python notes=True. Ordinary .hmk documents remain strict.
• Public Python compilation and export entry points are supported; internal AST, generated HTML structure, CSS class names, and runtime implementation objects may change.
• Browser layout and PDF rasterization can vary across Chromium, fonts, and platforms. Pin the compiler and browser environment for important repeatable exports. PDF bytes are not guaranteed identical.

Release contents

The versioned release provides a wheel, source archive, checksums, release inventory, examples, and these technical documents. The source archive includes tests and authoring resources. It excludes virtual environments, generated output, private notes, and credentials. Bundled third-party notices accompany their assets.

The public Hamen release record signs the exact release inventory digest with Ed25519. Individual artifacts are listed by SHA-256 in that inventory. Verify the signature against Hamen's public signing key, then compare downloaded file hashes. SHA-256 alone provides integrity, not proof of origin.

Maintainer release checklist

1. Update the central version in src/hamen_markup/_version.py, editor metadata, release notes, and documentation URLs.
2. Run Ruff, mypy, and the full pytest suite, including Chromium/PDF tests.
3. Generate technical documentation with python tools/build_docs.py --output OUTPUT.
4. Build wheel and source archive with python -m build. Install the wheel into a clean Python environment. Check CLI version, notes rendering, source-bundle roundtrip, and PDF export.
5. Verify source archive contents and bundled third-party assets. Generate checksums only after the artifacts are final.
6. Add the release's immutable versioned artifacts and docs to Hamen. Publish the product listing, then its signed release record. Never reuse a published version for different bytes.
7. Download the live artifacts and compare their hashes. Verify product, documentation, example, and signed-release routes after publication.

See validation evidence for what was actually run for this release.