docs(adr): ADR-0027 metadata-authoring — staged authoring, publish & promotion lifecycle#1427
Merged
Merged
Conversation
…commit engine Extract the visual-edit → database commit pipeline (validate → protect → OCC → L1 sys_metadata persist + L2 schema-sync DDL → changelog → notify) into a new transport-agnostic @objectstack/metadata-authoring package. Depends only on spec + metadata-core; reaches storage/DDL via injected ports whose adapters live in objectql, breaking the dependency cycle. https://claude.ai/code/session_01G33V5WWZc13ptd8ELBLkQg
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
size/m
documentation
Reframe the metadata-authoring package around two cadences instead of a per-edit commit: stage() accumulates drafts in a package-version workspace with zero runtime/DDL impact; publish() validates the set, plans+previews the migration, runs batched DDL, seals an immutable version, and activates via pointer swap. The publish unit is the package version, not per-person overlay rows. Adds a mainstream-platform comparison (Salesforce/ServiceNow/ Mendix/OutSystems/Hasura) and revives ADR-0016 §2's draft-workspace north-star. https://claude.ai/code/session_01G33V5WWZc13ptd8ELBLkQg
os-zhuang
changed the title
…fecycle
Detail the complete development business process grounded in the existing
data model (sys_package / sys_package_version{draft|published|deprecated} /
sys_package_installation pointer / sys_environment / sys_metadata.state):
actors+roles, the package-version state machine, phase-by-phase flow
(openDraft → stage → diff/validate → preview → publish → promote
Dev/Staging/Prod → rollback/deprecate/distribute), data-model mapping,
migration & data lifecycle with destructive gating by environment type,
concurrency/collaboration, approval gates, ports, and a gap analysis of
exists vs net-new. No new tables — the package is pure orchestration.
https://claude.ai/code/session_01G33V5WWZc13ptd8ELBLkQg
…dmap Add the complete capability map (authoring/migration/release/environments/ governance/recovery/distribution/collaboration/source-duality) marking what ships when, and a milestone roadmap (M0 seams → M1 staging → M2 publish → M3 promote+govern → M4 advanced migration/DX → M5 collaboration) where each milestone delivers standalone value, is non-breaking, and coexists with the §9 MVP. Bake in now (deliver later): ordered MigrationPlan for expand-contract zero-downtime migrations, per-target-environment DDL execution, and seal accepting either DB-draft or file/Git authoring (ADR-0006 two-flows-one-schema). Recommend M0+M1+M2 as the smallest end-to-end MVP. https://claude.ai/code/session_01G33V5WWZc13ptd8ELBLkQg
main introduced ADR-0025 (plugin package distribution) and ADR-0026 (client-side UI plugin distribution), so renumber the metadata-authoring ADR to 0027 and rename its slug to ...-lifecycle (the doc is the full authoring/publish/promotion lifecycle, not a per-edit commit). Add a boundary cross-reference: ADR-0025/0026 own how a sealed package is distributed/installed; ADR-0027 owns how it is authored, staged, sealed, and promoted — meeting at the sealed sys_package_version artifact. https://claude.ai/code/session_01G33V5WWZc13ptd8ELBLkQg
os-zhuang
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds ADR-0025 proposing
@objectstack/metadata-authoring— a server-side, transport-agnostic package that owns the metadata authoring lifecycle in two phases:sys_package_version(semver + checksum) → swap the env's active-version pointer. Rollback = swap the pointer back.Why
The first draft modelled a single
commit(change)that persisted + ran DDL + hot-activated on every edit — an anti-pattern for low-code (no mainstream platformALTER TABLEs production on each canvas click). This revision splits it intostage()+publish()and makes the package version — not a person's env-local overlay rows — the unit of work.The design is grounded in how mainstream systems handle this (comparison table in the ADR): Salesforce sandbox + Unlocked Package deploy, ServiceNow Update Sets, Mendix Team Server + deploy-time DB sync, OutSystems 1-Click Publish + LifeTime promotion, Hasura migrations. It revives ADR-0016 §2's draft-workspace north-star (the §9 MVP took a local-first shortcut).
Design highlights
stage()(draft, no DDL) vspublish()(batched DDL + seal + pointer-swap activation).spec+metadata-core; reaches storage/DDL/activation via injected ports (adapters inobjectql/runtime).schemaMode: external.Scope
Documentation only (ADR). No code changes yet — package scaffold (Phase 0) is a follow-up once the design is reviewed.
Builds on ADR-0003 / ADR-0005 / ADR-0008 / ADR-0010 / ADR-0016.
https://claude.ai/code/session_01G33V5WWZc13ptd8ELBLkQg