문제 README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서 10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고, verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서 참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거 드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint· check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다. 고른 방법 - 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로 적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로 적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다. - 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지 복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint, verify:documentation, check:i18n, check:design-system을 돈다 (FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다. - 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2 (c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울 수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다. 위험·한계 - 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지 않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다. - 드릴 시간이 lint·문서 검사 두 번만큼 는다. - 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기). 검증 - 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤 PASS_SCOPED. - 저장소에서 verify:documentation PASS_SCOPED, documentation-readiness 14건 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
76 lines
5.0 KiB
Markdown
76 lines
5.0 KiB
Markdown
# Contract compatibility and rollback rules
|
|
|
|
The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
|
|
assetManifestHash, releaseId)`. Versions are parsed numerically.
|
|
|
|
1. a change is additive only when it adds an optional field that every
|
|
reader of the previous version tolerates; see the boundary table below
|
|
2. breaking changes require a major version bump or a reader-first deployment
|
|
3. persisted cache is discarded unless an explicit tested migration exists
|
|
4. an incompatible config or API contract blocks product mount
|
|
5. rollback restores HTML, assets, runtime config, API compatibility, and
|
|
release manifest as one coherent set
|
|
|
|
## Per-boundary rules
|
|
|
|
Whether "add a field" is safe depends on the reader, not on the writer. Old
|
|
readers stay alive: several tabs, cached app shells and rollbacks are all
|
|
supported. At a `REJECT_UNKNOWN` boundary an added field is breaking, so the
|
|
reader that accepts it must ship before any writer sends it.
|
|
|
|
| Boundary | Reader policy | Adding a field or value | Code |
|
|
|---|---|---|---|
|
|
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `runtimeConfigV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
|
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `capabilityOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
|
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
|
| Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
|
| HTTP success/failure envelope (V3 with `responseEnvelope: "ENVELOPE_V1"`) | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/backend-envelope.ts` |
|
|
| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in the reference sample's contracts/reference-schemas.ts |
|
|
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` |
|
|
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` |
|
|
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` |
|
|
|
|
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids
|
|
vary per build because each downstream project installs its own features, and
|
|
one shared config document may cover several builds. The capability set is
|
|
fixed by the platform version, so an unknown capability means the config was
|
|
written for a newer platform; it is treated like any other strict config
|
|
addition.
|
|
|
|
## Schema change classifier and FE-GATE-014
|
|
|
|
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts`) answers
|
|
for a reader built against `before`. It is fail-closed: only a new property
|
|
under a reader without `additionalProperties: false` is `additive`. A removed
|
|
or changed property (type, enum, nullable, format, ...), a different required
|
|
set, or any other changed keyword is `breaking`. Nothing differs: `none`.
|
|
|
|
FE-GATE-014 (`config-compatibility`, `corepack pnpm verify:compatibility`)
|
|
runs `scripts/check-compatibility.ts`. It does two things:
|
|
|
|
1. Classifies the hand-written cases in `config/compatibility/fixtures.json`
|
|
and fails if any result differs from `expected`.
|
|
2. Compares the committed baseline
|
|
`config/compatibility/runtime-config.schema.baseline.json` with the current
|
|
runtime config schema, which is the same `z.toJSONSchema` output the build
|
|
writes to `dist/runtime-config.schema.json`
|
|
(`scripts/generate-build-manifest.ts`). A `breaking` result fails the gate.
|
|
|
|
The baseline stands for the schema that readers of the previous release
|
|
accept. When a breaking config change is intended, deploy the reader first (or
|
|
bump the config major version), then run
|
|
`corepack pnpm verify:compatibility --update-baseline` and commit the new
|
|
baseline with the change. The result is recorded in
|
|
`artifacts/release/compatibility.json`.
|
|
|
|
The current `apiContractVersion` check proves release/config coherence, not
|
|
provider conformance by itself. The target multi-protocol contract set binds
|
|
REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests,
|
|
protobuf source/descriptors/codegen profiles, Connect/gRPC-Web provider profiles,
|
|
ProtoJSON/HttpRule/generated OpenAPI/gateway artifacts, runtime schema/mapper
|
|
registries, and server-state policy digests as defined in
|
|
[API contract, Schema, Mapper, and Server State](../architecture/api-contract-schema-mapper-and-server-state.md).
|
|
Browser Protobuf and REST Gateway compatibility is further split in
|
|
[Protobuf browser transport and REST Gateway](../architecture/protobuf-browser-transport-and-rest-gateway.md);
|
|
binary/JSON/HTTP-route compatibility gates are not interchangeable.
|