1.0 is a stability commitment, not a rewrite — if you're on 0.3.x no code changes are required. The public library surface is the same as the 0.3.x releases; this version formalizes the promise with an explicit two-tier stability contract, a soft-deprecation-first policy, and a formal release.
What 1.0 Means for You
Rendro's public surface is organized into two tiers:
Tier-1 Stable — strict SemVer: Breaking changes only in a major version (1.x.x → 2.0.0). Additive changes are allowed in any minor. This tier covers the core document model and signing/protection APIs:
- Core document model:
Rendro.Document,Rendro.PageTemplate,Rendro.Section,Rendro.Metadata - Artifact struct:
Rendro.Artifact(the%Rendro.Artifact{}struct and its documented fields) - Signing surface:
Rendro.Sign—prepare/2,sign/2,augment/2,validate/2 - Protection surface:
Rendro.Protect—password/2 - Top-level pipeline functions:
Rendro.flow/2,Rendro.signature_field/2,Rendro.render_signed/3,Rendro.render_protected/3 - Diagnostics map common keys:
:leveland:typeare stable for adopters consuming:diagnosticsmaps
Tier-2 Evolving — additive-only within a major: These may break to follow upstream library majors, but will not introduce breaking changes within a major otherwise:
- Adapter modules:
Rendro.Adapters.PyHanko,Rendro.Adapters.Qpdf, and all otherRendro.Adapters.*modules - Extended diagnostics shape beyond the documented common keys (
:level,:type)
For the full two-tier contract, the byte-output carve-out, the "NOT covered by SemVer" list, and the deprecation policy, see guides/api_stability.md.
What's New Since 0.3.0
The 1.0.0 release consolidates all unreleased work from the 0.3.x → 1.0.0 period into a single public hex release:
Viewer evidence and CHANGELOG discipline: Every (surface × viewer) cell across forms, protection, signature widgets, signing preparation, signed artifacts, and long-lived signed artifacts is now terminal — recorded supported with a checked-in evidence file, or explicit_deferral with a named viewer-behavior reason. No cell is silently unverified. Evidence files live in priv/viewer_evidence/ and the operator recording recipe is in guides/viewer_evidence.md.
Batteries-included workflow features: Five data-driven recipes now ship on the three-rung escape hatch — Rendro.Recipes.Statement, Rendro.Recipes.Receipt, and Rendro.Recipes.Certificate alongside the existing Invoice/BrandedInvoice, with a deterministic page-numbering primitive ("Page X of Y" running headers/footers) and an executable reference Phoenix application. Optional adapter wiring for Oban/Threadline workflows and branding updates are included.
Formal API tiers and deprecation policy: The public surface is now machine-checked: a tiered manifest (priv/public_api.json) is verified by a docs-contract enforcement lane that fails CI on surface drift. The two-tier contract, soft-deprecation-first policy, and a formal Deprecations table (currently _None as of 1.0.0_) are published in guides/api_stability.md. Internal milestone labels are scrubbed from public guides.
Support Matrix
Viewer support posture is tracked per surface and per viewer. For the detailed per-surface support boundaries — interactive forms, signing preparation, signed artifacts, long-lived evidence, embedded files, curated links, protection, and viewer posture — see the ## Per-Surface Support Boundaries section of guides/api_stability.md.
The machine-readable index is priv/support_matrix.json, with each supported cell pointing to a recorded evidence file under priv/viewer_evidence/.
For full change history, see CHANGELOG.md.