docs(hemx): define v1 versioning policy
Add a compact semver and upgrade policy for v1: stable beginner APIs, stable wire/runtime compatibility, advanced escape-hatch tier, breaking-change rules, upgrade-note template, and release checklist. req: abi/001 req: abi/002 req: abi/003 req: abi/004 req: abi/005 req: public_api/001 req: public_api/002 req: public_api/005 req: runtime/003 req: runtime/004
This commit is contained in:
slhx agent
@@ -111,6 +111,7 @@ fall back to a full page reload when possible. See `docs/recipes/deploy-versioni
|
||||
Before a v1 release, the semver policy and upgrade notes should explicitly state
|
||||
which surfaces are stable: beginner generated helpers and handler shapes; the
|
||||
wire/runtime ABI; and advanced escape hatches that may remain integration-level.
|
||||
See `docs/versioning.md`.
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -104,7 +104,8 @@ For v1, document changes in three buckets:
|
||||
|
||||
Upgrade notes should explain what changed, whether generated code must be
|
||||
regenerated, whether `/hemx.js` must be rolled with the server, and what fallback
|
||||
users see if an old page talks to a new server.
|
||||
users see if an old page talks to a new server. Use `docs/versioning.md` as the
|
||||
release-policy checklist.
|
||||
|
||||
## Deployment checklist
|
||||
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
# v1 versioning and upgrade policy
|
||||
|
||||
hemx v1 should be boring to upgrade: beginner apps can rely on the generated
|
||||
helper and handler model, while advanced escape hatches remain explicitly named
|
||||
and easier to audit. This policy defines what must be stable for v1 and how to
|
||||
ship breaking changes without hiding incompatibility behind runtime magic. req: abi/001 req: public_api/001
|
||||
|
||||
## Stability tiers
|
||||
|
||||
### Stable beginner API
|
||||
|
||||
These are the v1 normal path and require semver-major treatment for breaking
|
||||
changes:
|
||||
|
||||
- `#[hemx::surface]`, `#[hemx::app]`, `#[hemx::component]`, `#[hemx::handler]`,
|
||||
and `#[hemx::form]`
|
||||
- generated component helpers for slots, keyed partials, forms, handles, page
|
||||
targets, class tokens, and events
|
||||
- `hemx::page(...)` for page-boundary rendering
|
||||
- tuple `IntoEffect` composition
|
||||
- `Result<impl IntoEffect, E>` handlers with `IntoHandlerFailure`
|
||||
- generated form commands such as `clear`, `reset`, `error`, and `focus`
|
||||
- generated keyed commands such as `append`, `replace`, and `remove`
|
||||
|
||||
A change is breaking if a production-shaped app like `examples/saas` must rewrite
|
||||
normal handler/template code that was using those APIs correctly. req: examples/001 req: canonical_authoring/006
|
||||
|
||||
### Stable compatibility contract
|
||||
|
||||
These must remain explicit and fail closed when incompatible:
|
||||
|
||||
- Surface schema version consumed by `hemx_build`
|
||||
- generated symbols and deterministic resource allocation inputs
|
||||
- EffectBatch wire/schema ABI
|
||||
- JavaScript runtime ABI
|
||||
- build fingerprint inputs and mismatch behavior
|
||||
|
||||
An incompatible wire/runtime change must bump the relevant ABI version and cause
|
||||
old pages or old runtimes to refuse partial updates rather than silently applying
|
||||
wrong effects. req: abi/002 req: abi/003 req: abi/004 req: failure/005
|
||||
|
||||
### Advanced escape hatches
|
||||
|
||||
These are public but advanced. They may evolve faster, but every change still
|
||||
needs a migration note and must not leak into beginner docs:
|
||||
|
||||
- raw effects and batches
|
||||
- manual registries
|
||||
- low-level resource ids and raw targets
|
||||
- raw HTML/render/target construction
|
||||
- runtime hooks and SSE internals
|
||||
- island internals and custom integration glue
|
||||
|
||||
Advanced APIs are for integration crates, tests, migrations, or explicit leaf
|
||||
boundaries. They are not a second beginner API. req: public_api/002 req: public_api/005
|
||||
|
||||
## What counts as breaking
|
||||
|
||||
Breaking for the beginner API:
|
||||
|
||||
- renaming generated helper methods or changing their return contracts
|
||||
- requiring manual registry wiring for canonical apps
|
||||
- requiring user-authored JavaScript or selector targeting for ordinary forms,
|
||||
partial swaps, page swaps, or SSE/polling
|
||||
- moving validation/error UI off generated form helpers
|
||||
- changing handler argument inference so existing valid handlers stop compiling
|
||||
- changing `Result<impl IntoEffect, E>` mapping so app errors no longer map at
|
||||
the integration boundary
|
||||
|
||||
Breaking for compatibility:
|
||||
|
||||
- changing effect wire encoding without an ABI bump
|
||||
- changing runtime target lookup semantics without a fingerprint/ABI bump
|
||||
- changing generated id allocation inputs without a fingerprint change
|
||||
- allowing mismatched server/runtime builds to apply partial updates
|
||||
|
||||
Not breaking:
|
||||
|
||||
- improving diagnostics while keeping spans and fixes user-facing
|
||||
- adding generated helpers that are aliases around existing behavior when they
|
||||
remove real friction
|
||||
- adding new advanced escape hatches that are clearly named and isolated
|
||||
- adding production recipes for providers outside core
|
||||
- changing examples to better express the canonical path, when the documented API
|
||||
remains compatible
|
||||
|
||||
## Upgrade note template
|
||||
|
||||
Every release with public API, generated ABI, runtime, or recipe changes should
|
||||
include upgrade notes with this shape:
|
||||
|
||||
````md
|
||||
## Upgrade to hemx X.Y.Z
|
||||
|
||||
### Who is affected
|
||||
- Beginner app code: yes/no
|
||||
- Generated helpers: yes/no
|
||||
- Wire/runtime ABI: yes/no
|
||||
- Advanced escape hatches: yes/no
|
||||
- Recipes/examples only: yes/no
|
||||
|
||||
### Required actions
|
||||
- Regenerate generated code with `cargo check` or your normal build.
|
||||
- Deploy server and `/hemx.js` from the same release if ABI/fingerprint changed.
|
||||
- Update any renamed helpers or advanced calls listed below.
|
||||
|
||||
### Compatibility behavior
|
||||
- Old page + new server: reload/fail closed/compatible
|
||||
- New page + old server: reload/fail closed/compatible
|
||||
- Rolling deploy requirement: sticky release routing / normal routing
|
||||
|
||||
### Migrations
|
||||
- Before: ...
|
||||
- After: ...
|
||||
|
||||
### Verification
|
||||
```sh
|
||||
cargo run -p hemx-xtask -- test
|
||||
cargo check --workspace
|
||||
redgate health --strict
|
||||
```
|
||||
````
|
||||
|
||||
## Release checklist
|
||||
|
||||
Before tagging a v1-compatible release:
|
||||
|
||||
- `examples/v0` and `examples/saas` compile and test without raw ids, raw effects,
|
||||
selector targeting, manual registries, raw render/lower calls, or user-authored
|
||||
UI JavaScript in the normal path. req: examples/004 req: examples/005
|
||||
- `docs/diagnostics.md` describes any new common error class in user language.
|
||||
req: diagnostics/001 req: diagnostics/002
|
||||
- `docs/recipes/deploy-versioning.md` remains accurate for runtime asset and
|
||||
fingerprint behavior.
|
||||
- Any incompatible generated ABI/runtime change bumps the relevant ABI/fingerprint
|
||||
inputs and has tests for fail-closed behavior. req: abi/005
|
||||
- Advanced APIs touched by the release are still named as escape hatches in docs.
|
||||
- Upgrade notes state whether users must regenerate code, redeploy `/hemx.js`, or
|
||||
change app code.
|
||||
|
||||
## Policy for v1 cutover
|
||||
|
||||
v1 is ready to cut only when the normal path can stay stable for the canonical
|
||||
SaaS tutorial: hemplate templates, typed handlers, generated helpers, tuple
|
||||
effects, result error mapping, page/push shape, explicit provider adapters,
|
||||
plain CSS, and one island boundary. If stabilizing one of those surfaces would
|
||||
require adding runtime negotiation, selector retargeting, a client state store, or
|
||||
provider-specific core code, defer the feature or keep it advanced instead of
|
||||
weakening the v1 contract. req: runtime/003 req: runtime/004 req: laws/004
|
||||
Reference in New Issue
Block a user