Skip to content

Commit 889e809

Browse files
dmealingclaude
dmealing
and
claude
committed
docs(1.0): ADR-0035 + readiness checklist for the 1.0 stability commitment
Frames 1.0 as the stability line enabled by scaffold-and-own (ADR-0034, which shrank the compat surface to the metamodel spine + CLI + wire + scaffold contract) and signalled mature by the metaobjects-audit skill. Records the compat policy, the version-line unification recommendation (all ports → 1.0.0), and the breaking-change consolidation gating. Open [RATIFY] decisions: version unification, FR-024 land/defer, deprecated codegen-ts/generators export, cross-port own-your-codegen. ADR Proposed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LuZWKnWzYGVnESijL7uuky
1 parent b40f061 commit 889e809

2 files changed

Lines changed: 200 additions & 0 deletions

File tree

‎docs/1.0-readiness.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# MetaObjects 1.0 readiness checklist
2+
3+
A living checklist for cutting the first **stable** release. The strategy + the
4+
compatibility surface it commits to are in
5+
[ADR-0035](../spec/decisions/ADR-0035-one-zero-stability-commitment-and-version-unification.md).
6+
7+
**Thesis:** scaffold-and-own (ADR-0034) shrank the surface 1.0 must keep stable to
8+
the **metamodel spine + CLI + wire format + the scaffold-and-own contract** — the
9+
generated code is owned/disposable, so its internals are no longer a public API. The
10+
`metaobjects-audit` skill is the maturity signal that the surface has set. 1.0 is
11+
gated less by features than by **dropping the breaking-change rate** so we can
12+
promise "no breaking until 2.0."
13+
14+
Status legend: ✅ done · 🔶 in progress · ⬜ not started · ❓ **[RATIFY]** decision needed.
15+
16+
---
17+
18+
## A. Strategic decisions (ratify first — they shape everything else)
19+
20+
- ❓ **A1. Version-line unification.** Unify all ports to `1.0.0` (Maven `7.x → 1.0.0`)
21+
vs keep independent lines (npm `1.0`, Maven `8.0`). *ADR-0035 §2 recommends unify.*
22+
- ❓ **A2. FR-024 declared-API: land vs defer.** Land `api.*`/`operation.*`/`binding.*`
23+
before 1.0, or defer post-1.0 with the vocabulary *reserved but unregistered* (so
24+
adding it later is additive). *Tracked in #10.*
25+
- ❓ **A3. Deprecated `@metaobjectsdev/codegen-ts/generators` export.** Remove at 1.0
26+
(1.0 is the natural major) vs retain one more line.
27+
- ❓ **A4. Cross-port "own your codegen."** Ratify per-port-idiomatic (TS `meta init`;
28+
JVM/Python/C# via build config) **and document it**, vs close a parity gap first.
29+
30+
---
31+
32+
## B. Compatibility surface (the 1.0 promise)
33+
34+
- ⬜ **B1. Publish the compat policy** (ADR-0035 §1, consumer-facing): what semver
35+
covers post-1.0 — metamodel vocabulary, canonical/YAML format, wire/normalization,
36+
CLI surface, scaffold-and-own contract — and what it does *not* (generator
37+
internals, runtime helper internals, reserved/experimental vocab).
38+
- ⬜ **B2. Write the `0.x → 1.0` migration guide.** Consolidate the breaking changes
39+
adopters must absorb (verify strict-default, jsonb open-bag parsed-value, the
40+
deprecated-export removal if A3=remove, any FR-024 vocab if A2=land).
41+
42+
## C. Metamodel freeze (the durable spine)
43+
44+
- ✅ **C1. `registry-conformance` enforces the vocabulary** byte-identically across all
45+
5 ports.
46+
- 🔶 **C2. No pending vocabulary churn.** Resolve A2 (FR-024). Audit the registry for
47+
anything still experimental or under active change.
48+
- ✅ **C3. The last breaking metamodel/wire moves landed in `0.14.0`/`7.6.0`** —
49+
verify strict-default (ADR-0023 enforcement) + the jsonb open-bag parsed-value
50+
contract. Nothing else breaking queued on those surfaces.
51+
52+
## D. CLI + scaffold-and-own contract
53+
54+
- ✅ **D1. `verify` strict-by-default + `--lax`/`-Dmeta.lax`** consistent across all 4
55+
CLI ports (shipped 0.14.0/7.6.0).
56+
- 🔶 **D2. CLI flag surface documented + frozen** — `init`/`gen`/`verify` (+ subverbs,
57+
`--lax`, `--template-spec`, target/output flags) per port, locked against the CLI
58+
architecture (ADR-0015) and surfaced in one matrix.
59+
- 🔶 **D3. Scaffold-and-own contract stable (TS)** — what `meta init` scaffolds + the
60+
`Generator` interface owned templates implement; resolve A3.
61+
- ⬜ **D4. "Own your codegen" documented for every port** (resolve A4): the TS
62+
`meta init` flow and the JVM/Python/C# build-config equivalents, side by side.
63+
64+
## E. Cross-port conformance + wire contract
65+
66+
- ✅ **E1. All shared corpora green** (metamodel, render, persistence, api-contract,
67+
registry, verify) on `main`.
68+
- ✅ **E2. Cross-port api-contract jsonb gate wired** for all 5 ports (TS/Python +
69+
Java/Kotlin/C#).
70+
- 🔶 **E3. Sweep for any per-port-only contract behavior** that should be cross-port
71+
gated before the freeze (the gate caught 3 real bugs in 0.14.0 — assume more lurk).
72+
73+
## F. Adoption proof (the audit as readiness signal)
74+
75+
- ✅ **F1. `metaobjects-audit` skill shipped** + run against two real deep adopters.
76+
- 🔶 **F2. A real adopter reaches "Deep/Exemplary" with the CI drift gate wired** —
77+
the strongest evidence the surface is stable enough to promise. (Both audited
78+
adopters were Deep; neither had the drift gate enforced in CI yet — closing that on
79+
at least one adopter is the proof point.)
80+
- ⬜ **F3. Fold the audit findings that point at the framework back in** (e.g. the
81+
jsonb runtime-write gaps the gate surfaced) so 1.0 ships without known adoption
82+
friction.
83+
84+
## G. Release mechanics for the 1.0 cut
85+
86+
- ⬜ **G1. Execute A1** (version bump across all ports to the unified number).
87+
- ⬜ **G2. Remove the deprecated export** if A3=remove (one-time).
88+
- ⬜ **G3. A quiet period** — at least one `0.x`/`7.x` release after the consolidation
89+
window with **no breaking changes**, to prove the rate has actually dropped.
90+
- ⬜ **G4. Cut 1.0** through the `releasing` skill (RC → smoke → confirm → promote),
91+
with the migration guide + compat policy published alongside.
92+
93+
---
94+
95+
_Last updated 2026-06-29. Owner: maintainer. Update the status marks as items land;
96+
ratify the §A decisions to unblock the rest._

‎spec/decisions/ADR-0035-one-zero-stability-commitment-and-version-unification.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# ADR-0035: MetaObjects 1.0 — stability commitment, compat policy, and version-line unification
2+
3+
## Status
4+
5+
**Proposed** (2026-06-29). Companion checklist: [`docs/1.0-readiness.md`](../../docs/1.0-readiness.md).
6+
7+
This ADR frames the decisions a 1.0 release commits to; the bracketed **[RATIFY]**
8+
items are open calls for the maintainer to confirm before this moves to *Accepted*.
9+
It does not itself change any code or contract.
10+
11+
## Context
12+
13+
Two recent shifts make 1.0 both *achievable* and *meaningful*, and they are the
14+
turning point:
15+
16+
1. **Scaffold-and-own (ADR-0034).** Generated code is now owned and disposable in
17+
the consumer's repo; the library ships the engine + reference templates that
18+
`meta init` copies. This **collapses the public surface** that 1.0 must keep
19+
stable — the generator internals stop being an API consumers couple to.
20+
2. **The `metaobjects-audit` skill.** The project can now assess how well an app
21+
has adopted the standard. You can only audit an adoption surface that is stable
22+
enough to *define* "well-integrated" — the audit is the maturity signal that the
23+
surface has set.
24+
25+
Against that, the honest tension: the `0.14.0`/`7.6.0` line just shipped **breaking
26+
changes in a minor** (verify strict-by-default; the jsonb open-bag contract). 1.0's
27+
entire value is the *compat promise*, so 1.0 is gated less by "are the features
28+
there" than by "has the breaking-change rate dropped enough to commit to
29+
no-breaking-until-2.0." Three things are still in motion: FR-024 (declared
30+
`api.*`/`operation.*`/`binding.*` — net-new vocabulary), the deprecated
31+
`@metaobjectsdev/codegen-ts/generators` export ("removal in a future major"), and
32+
the fact that "own your codegen" is TS-led (`meta init`) while the JVM/Python/C#
33+
ports own generators via build config.
34+
35+
The version lines also diverge: npm/PyPI/NuGet are on `0.x`; Maven Central is on
36+
`7.x` (a line the Java project inherited, never a public semver commitment).
37+
38+
## Decision
39+
40+
### 1. What 1.0 stabilizes — the compat surface (semver applies; breaking ⇒ 2.0)
41+
42+
**Covered** (a breaking change here requires a MAJOR bump after 1.0):
43+
- **The metamodel vocabulary** — the registered type/subtype/attribute set, enforced
44+
by `registry-conformance` (`expected-registry.json`). This is *the* durable spine.
45+
- **The canonical authoring + interchange format** — canonical JSON keywords/`@`-attr
46+
rules (ADR-0006), sigil-free YAML, `extends`/`@via` grammar, package `::` syntax.
47+
- **The wire / normalization contract** — cross-port serialized form (currency minor
48+
units, pagination, native-return-type contract ADR-0019, jsonb parsed-value).
49+
- **The CLI command surface** — `init` / `gen` / `verify` (per-port: `meta`,
50+
`dotnet meta`, `mvn metaobjects:*`, `metaobjects`) and their *documented* flags
51+
(incl. `--lax`/`-Dmeta.lax`, the verify subverbs).
52+
- **The scaffold-and-own contract** — what `meta init` scaffolds and the `Generator`
53+
interface owned templates implement.
54+
55+
**Not covered** (may change in a minor):
56+
- Generator internals and the reference templates themselves (owned/disposable).
57+
- Runtime-library helper internals (best-effort; idiomatic per port).
58+
- Anything explicitly marked experimental/reserved and not yet in the registry.
59+
60+
### 2. Version-line unification — **[RATIFY]**
61+
62+
**Recommendation: unify all ports to `1.0.0`** at the 1.0 line (npm/PyPI/NuGet
63+
`0.x → 1.0.0`; Maven Central `7.x → 1.0.0`). 1.0 means "v1 of the unified
64+
*standard*"; the Maven `7.x` line was inherited internal versioning, not a public
65+
semver promise, and unifying ends the confusing `0.x`-vs-`7.x` split exactly when we
66+
are declaring one standard. Maven's number *decreases* — defensible as a one-time
67+
reset, and 1.0 is the moment to make that statement.
68+
69+
*Alternative (rejected unless ratified otherwise):* keep independent lines
70+
(npm `→1.0.0`, Maven `→8.0.0`) — perpetuates the split the standard exists to erase.
71+
72+
### 3. Gating items — the breaking-change consolidation window — **[RATIFY each]**
73+
74+
Treat the next one or two `0.x`/`7.x` releases as the window to land every breaking
75+
change we still want, then freeze. Before cutting 1.0:
76+
- **FR-024 declared-API:** land it, **or** explicitly defer post-1.0 with
77+
`api.*`/`operation.*`/`binding.*` *reserved but unregistered* (so adding them later
78+
is additive, not breaking). **[RATIFY: land vs defer]**
79+
- **Deprecated `codegen-ts/generators` export:** remove at 1.0 (1.0 is the natural
80+
major for it), **or** consciously retain one more line. **[RATIFY: remove vs keep]**
81+
- **Cross-port "own your codegen":** ratify that it is *per-port-idiomatic* (TS
82+
`meta init`; JVM/Python/C# via build config) and **document that explicitly**, OR
83+
close a parity gap first. **[RATIFY: idiomatic-and-document vs close-gap]**
84+
- **Metamodel freeze:** no pending vocabulary churn; `registry-conformance` is the
85+
enforcer; the jsonb + verify-strict contracts (just shipped) are the last
86+
breaking moves on those surfaces.
87+
- **Cross-port conformance complete:** all corpora green; the cross-port
88+
api-contract jsonb gate fully wired (TS/Python/Java/Kotlin/C#).
89+
- **Migration + policy docs:** a `0.x → 1.0` migration guide and a published
90+
compatibility policy (this ADR's §1, consumer-facing).
91+
92+
## Consequences
93+
94+
- After 1.0, a breaking change to the metamodel vocabulary, the canonical/wire
95+
format, the CLI surface, or the scaffold-and-own contract requires a **2.0**. The
96+
small stable surface (a consequence of scaffold-and-own) makes that a realistic
97+
commitment, not a straitjacket.
98+
- The deprecation removal and the version-line unification are **one-time 1.0 moves**
99+
— do them at the boundary, not after.
100+
- The `metaobjects-audit` adoption tiers become a *de facto* readiness signal: a real
101+
adopter reaching "Deep/Exemplary" with the drift gate wired is evidence the surface
102+
is stable enough to promise.
103+
- Until ratified, the open **[RATIFY]** items are the agenda for the 1.0 planning,
104+
tracked in `docs/1.0-readiness.md`.

0 commit comments

Comments
 (0)