문제: docs/runbooks, docs/security, docs/styling/design-tokens.md, docs/accessibility, docs/contracts, docs/testing/taxonomy.md와 src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다. PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code, 기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로 둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장 끝만 바꾼다. 위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임 문체를 더하면 verify:documentation이 실패한다. 검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다. 문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
83 lines
6.1 KiB
Markdown
83 lines
6.1 KiB
Markdown
# 계약 호환성과 rollback 규칙
|
|
|
|
차단 기준이 되는 tuple은 `(buildId, configSchemaVersion, apiContractVersion,
|
|
assetManifestHash, releaseId)`이다. version은 숫자로 파싱한다.
|
|
|
|
1. 변경이 추가(additive)로 인정되는 것은 이전 version의 모든 reader가 받아들이는
|
|
선택 필드를 더할 때뿐이다. 아래 경계별 표를 본다
|
|
2. 깨지는(breaking) 변경은 major version을 올리거나 reader를 먼저 배포해야 한다
|
|
3. 저장된 cache는 테스트된 명시적 migration이 없으면 버린다
|
|
4. 호환되지 않는 config나 API 계약은 제품 mount를 막는다
|
|
5. rollback은 HTML, asset, runtime config, API 호환성, release manifest를 하나의
|
|
일관된 묶음으로 되돌린다
|
|
|
|
## 경계별 규칙
|
|
|
|
"필드 추가"가 안전한지는 쓰는 쪽(writer)이 아니라 읽는 쪽(reader)에 달려 있다.
|
|
옛 reader는 계속 살아 있다. 여러 탭, cache된 앱 셸, rollback을 모두 지원하기
|
|
때문이다. `REJECT_UNKNOWN` 경계에서는 필드를 더하면 깨진다. 그래서 그 필드를
|
|
받아들이는 reader를 먼저 배포해야 한다. 어떤 writer든 그 뒤에야 그 필드를 보낼
|
|
수 있다.
|
|
|
|
| 경계 | reader 정책 | 필드나 값 추가 | 코드 |
|
|
|---|---|---|---|
|
|
| Runtime config V2 (`/config.json`) | 엄격한(strict) object. `CONFIG_SCHEMA_VERSION`은 리터럴 `"2.0"` | 깨짐 | `src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema` |
|
|
| `CAPABILITY_OVERRIDES` | 엄격함. 모르는 capability는 거부 | 깨짐 | `src/contracts/release-artifacts.ts`의 `capabilityOverrideArtifactSchema` |
|
|
| `FEATURE_OVERRIDES` | record. 모르는 feature id는 무시 | 추가로 인정 | `src/contracts/release-artifacts.ts`의 `featureOverrideArtifactSchema` |
|
|
| Release manifest V2 | 엄격한 object | 깨짐 | `src/contracts/release-artifacts.ts`의 `releaseManifestV2ArtifactSchema` |
|
|
| HTTP 성공·실패 envelope (V3에서 `responseEnvelope: "ENVELOPE_V1"`) | 엄격한 object(`meta`는 걸러 냄) | 깨짐 | `src/adapters/http/backend-envelope.ts`의 `successEnvelopeSchema`, `failureEnvelopeSchema` |
|
|
| HTTP V3 응답 DTO (feature의 것) | `.strip()`이 모르는 필드를 버림 | 추가로 인정 | `create:feature`가 만드는 feature의 `contracts/<base>-schemas.ts`에 있는 `<camel>ItemDtoSchema` |
|
|
| Realtime envelope | 정확한 key 집합. 모르는 `eventType`은 `MALFORMED_EVENT` | 깨짐 | `src/adapters/realtime/event-codec.ts`의 `decodeUnsafe` |
|
|
| Browser RPC 전송 오류 code | 닫힌 어휘. 모르는 code는 protocol 위반 | 깨짐 | `src/adapters/browser-rpc/browser-rpc-runtime.ts`의 `decodeTransportFailure` |
|
|
| 저장된 클라이언트 storage | version이 붙은 key. 호환되지 않는 값은 버림 | 새 key version을 쓴다 | `src/contracts/storage-keys.ts`의 `defineStorageKey` |
|
|
|
|
응답 DTO를 엄격하게 바꾸면 이 표에서 그 행이 바뀐다. `RESPONSE` schema의
|
|
FE-REG-SCHEMA 행이 `STRIP_UNKNOWN`에서 `REJECT_UNKNOWN`으로 바뀌면
|
|
`check:registries`가 이를 깨지는 변경(`response-reader-narrowed`)으로 판정한다.
|
|
그래서 그 변경에는 registry 증거가 필요하다(1105/07-02).
|
|
|
|
`CAPABILITY_OVERRIDES`와 `FEATURE_OVERRIDES`는 일부러 다르게 둔다. feature id는
|
|
빌드마다 다르다. 다운스트림 프로젝트마다 자기 feature를 설치하기 때문이다.
|
|
그리고 공유 config 문서 하나가 여러 빌드를 덮을 수 있다. capability 집합은
|
|
platform version이 정한다. 그래서 모르는 capability가 있다는 것은 그 config가 더
|
|
새 platform을 위해 쓰였다는 뜻이다. 이것은 다른 엄격한 config 추가와 똑같이
|
|
다룬다.
|
|
|
|
## Schema 변경 분류기와 FE-GATE-014
|
|
|
|
`classifyObjectSchemaChange`(`src/contracts/compatibility.ts`)는 `before`를
|
|
기준으로 만든 reader 입장에서 답한다. fail closed로 동작한다:
|
|
`additionalProperties: false`가 없는 reader 아래에 새 property를 더한 경우만
|
|
`additive`다. property를 지우거나 바꾸는 것(type, enum, nullable, format 등),
|
|
required 집합이 달라지는 것, 그 밖의 keyword가 바뀌는 것은 모두 `breaking`이다.
|
|
아무것도 다르지 않으면 `none`이다.
|
|
|
|
FE-GATE-014(`config-compatibility`, `corepack pnpm verify:compatibility`)는
|
|
`scripts/check-compatibility.ts`를 실행한다. 이 스크립트는 두 가지를 한다.
|
|
|
|
1. `config/compatibility/fixtures.json`에 손으로 쓴 사례를 분류하고, 결과가
|
|
하나라도 `expected`와 다르면 실패한다.
|
|
2. commit된 기준선 `config/compatibility/runtime-config.schema.baseline.json`을
|
|
지금 runtime config schema와 비교한다. 지금 schema는 빌드가
|
|
`dist/runtime-config.schema.json`에 쓰는 것과 같은 `z.toJSONSchema`
|
|
출력이다(`scripts/generate-build-manifest.ts`). 결과가 `breaking`이면 gate가
|
|
실패한다.
|
|
|
|
기준선은 이전 release의 reader가 받아들이는 schema를 나타낸다. 깨지는 config
|
|
변경을 의도했다면 reader를 먼저 배포한다(또는 config major version을 올린다).
|
|
그다음 `corepack pnpm verify:compatibility --update-baseline`을 실행하고, 새
|
|
기준선을 변경과 함께 commit한다. 결과는 `artifacts/release/compatibility.json`에
|
|
기록된다.
|
|
|
|
지금의 `apiContractVersion` 검사는 release와 config가 서로 맞는다는 것을
|
|
증명한다. 그것만으로 provider가 계약을 지킨다는 것까지 증명하지는 않는다. 목표로
|
|
하는 다중 protocol 계약 묶음은
|
|
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)에
|
|
정의된 대로 다음을 묶는다: REST/OpenAPI artifact, GraphQL schema와
|
|
persisted-operation manifest, protobuf source·descriptor·codegen profile,
|
|
Connect/gRPC-Web provider profile, ProtoJSON·HttpRule·생성된 OpenAPI·gateway
|
|
artifact, runtime schema·mapper registry, server-state 정책 digest.
|
|
브라우저 Protobuf와 REST Gateway 호환성은
|
|
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)에서
|
|
더 나눈다. binary·JSON·HTTP route 호환성 gate는 서로 바꿔 쓸 수 없다.
|