10 KiB
10 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Google AIP-180 — Backwards compatibility | official-doc | https://google.aip.dev/180 | reviewed | high |
|
|
|
2026-05-22 | 2026-05-27 |
Google AIP-180 — Backwards compatibility
Layer:
raw/official-docs/— Google API Improvement Proposals 의 backwards compatibility 정책. ca-tmpl breaking change catalog 7행 분류의 reference.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-api-compatibility-deprecation-contract | ca-tmpl breaking change catalog 7행 (remove field / rename / change type / narrow enum / add required request field / add optional response field / change error code) 분류의 표준 정합성 검증 근거 + Stripe / AIP 모델 비교 |
| raw/project-notes/ca-skeleton-operational-contract | API 호환성 정책 섹션 (catalog 7행 정당화 근거) |
컨텍스트 / 왜 저장했는지
ca-tmpl breaking change catalog 7행 분류 (remove field, rename, change type, narrow enum, add required request field, add optional response field, change error code) 가 AIP-180 의 분류와 어떻게 정합/차이가 있는지 검증하기 위함. canonical 승급 시 catalog 정당화에 필요. Google AIP 는 internal Google API 의 design guideline 이지만 외부 개발자에게도 reference 로 널리 인용됨.
출처 / Source
- 원본 URL: https://google.aip.dev/180
- 관련 AIP: AIP-181 (Stability levels), AIP-185 (Versioning)
- 아카이브 URL: (미수집)
- 저자 / 조직: Google (API Improvement Proposals working group)
- 발행일: continuously updated (AIP-180 자체에 fixed 발행일 없음)
- 마지막 확인일: 2026-05-27 (WebFetch 재검증 성공 — 5개 quote 모두 verbatim 일치, strength
needs-confirmation→official-vendor-doc으로 upgrade. [2026-05-25 capture] verbatim 보존본 유지). 현재 section headings: Guidance / Adding components / Removing or renaming components / Moving components between files / Moving into oneofs / Changing the type of fields / Changing string length / Changing resource names / Semantic changes / Further reading / Rationale / Changelog
핵심 인용 / Key quotes (verbatim)
[§Removing components, captured 2026-05-22] "Existing components (interfaces, methods, messages, fields, enums, or enum values) must not be removed from existing APIs in the same major version."
[§Renaming components, captured 2026-05-22] "Renaming a component is semantically equivalent to 'remove and add'."
[§Default behavior, captured 2026-05-22] "Any field being populated by clients must have a default behavior matching the behavior before the field was introduced."
[§Required fields, captured 2026-05-22] "New required fields must not be added to existing request messages or resources."
[§Core principle, captured 2026-05-22] "Existing client code must not be broken by a service updating to a new minor or patch release."
[2026-05-27 verified — WebFetch 재검증 성공]: 본 5개 quote (AIP180-C1 ~ AIP180-C5) 모두 https://google.aip.dev/180 live 페이지에서 FOUND VERBATIM. strength
needs-confirmation→official-vendor-doc으로 upgrade. [2026-05-25 capture] verbatim 본문 그대로 유지. AIP-181 / AIP-185 와의 cross-reference 는 별도 raw 작성 시 재확인.
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| AIP180-C1 | 같은 major version 안에서 기존 component (interface / method / message / field / enum / enum value) 를 제거하면 안 됨 (must not) |
[§Removing or renaming components, captured 2026-05-22 + 2026-05-27 verified verbatim] "Existing components (interfaces, methods, messages, fields, enums, or enum values) must not be removed from existing APIs in the same major version." | official-vendor-doc [2026-05-27 verified] |
Google API design (외부 reference 로 인용 가능) | 다른 major version (v1 → v2) 으로 이동 시 제거 정책은 별도 (AIP-181 / AIP-185 영역) |
| AIP180-C2 | component renaming 은 의미상 "remove + add" 와 동등 (즉 rename 은 breaking) | [§Removing or renaming components, captured 2026-05-22 + 2026-05-27 verified verbatim] "Renaming a component is semantically equivalent to 'remove and add'." | official-vendor-doc [2026-05-27 verified] |
rename 결정의 breaking 분류 | alias / 양쪽 동시 노출 같은 mitigation 정책은 본 인용에 없음 — C1 과 함께 same major version 안에서는 사실상 금지 |
| AIP180-C3 | client 가 채우는 모든 field 는 도입 이전 동작과 일치하는 default behavior 를 가져야 함 (must) |
[§Adding components / Default behavior, captured 2026-05-22 + 2026-05-27 verified verbatim] "Any field being populated by clients must have a default behavior matching the behavior before the field was introduced." | official-vendor-doc [2026-05-27 verified] |
새 optional field 추가 시 default 동작 정책 | 모든 새 field 가 optional 이어야 한다는 뜻은 아님 — C4 가 required field 별도 다룸 |
| AIP180-C4 | 기존 request message / resource 에 새 required field 를 추가하면 안 됨 (must not) |
[§Adding components / Required fields, captured 2026-05-22 + 2026-05-27 verified verbatim] "New required fields must not be added to existing request messages or resources." | official-vendor-doc [2026-05-27 verified] |
새 field 추가 시 required vs optional 결정 | 새 endpoint / 새 message 에서는 required field 자유 — 본 인용은 기존 message 만 |
| AIP180-C5 | 서비스가 minor 또는 patch release 로 업데이트되었을 때 기존 client code 가 깨지면 안 됨 (must not, 핵심 원칙) |
[§Guidance / Core principle, captured 2026-05-22 + 2026-05-27 verified verbatim] "Existing client code must not be broken by a service updating to a new minor or patch release." | official-vendor-doc [2026-05-27 verified] |
semver 의 minor / patch release 호환성 | major version bump 시 breaking change 허용 여부는 본 인용 범위 밖 (AIP-185 영역) |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것 (2026-05-22 capture + 2026-05-27 WebFetch verbatim 재검증):
AIP180-C1: 같은 major version 안에서 component 제거 금지AIP180-C2: rename = breakingAIP180-C3: 새 field 의 default 동작은 이전과 일치해야 함AIP180-C4: 기존 message 에 새 required field 추가 금지AIP180-C5: minor/patch 에서 client breaking 금지
- 이 자료가 증명하지 않는 것:
- 다른 major version (v1 → v2) 으로의 migration 정책 — AIP-185 영역
- deprecation 통지 / window / sunset 정책 — AIP-180 본문에 부분만 있을 수 있음 (재확인 필요)
- error code (status code / error enum) 변경의 정확한 분류 — AIP-180 은 enum value 제거 금지 원칙으로 같은 결론에 도달하지만 명시적 "error code change" 행은 본 인용에 없음
- CI breaking diff 자동 차단 같은 운영 메커니즘
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 2026-05-27 시점 AIP-180 본문 재확인 (continuously updated)
- ca-tmpl 의
migration window 90d/30d가 AIP-180 의 "절대 제거 금지" (C1) 와 다른 정책임을 명시 - ca-tmpl 의
narrow enum 을 new version 으로정책이 AIP-180 의 "enum value 제거 금지" 와 호환 가능한지 (new version 도입 시점에서는 호환)
ca-tmpl 함의 (내 프로젝트 해석)
본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 source-summary 로 옮겨야 함.
AIP-180 과 ca-tmpl catalog 정합
| catalog 행 | AIP-180 분류 (인용 근거) | 일치 여부 |
|---|---|---|
| remove response field | breaking — AIP180-C1 ("must not be removed") |
일치 |
| rename response field | breaking — AIP180-C2 ("remove and add") |
일치 |
| change field type/format | breaking — AIP180-C5 (client code breaks) |
일치 (간접) |
| narrow enum values | breaking — AIP180-C1 (enum values 도 component) |
일치 |
| add required request field | breaking — AIP180-C4 (명시적 금지) |
일치 |
| add optional response field | additive — AIP180-C3 (default 동작 보장 시) |
일치 |
| change error code | breaking for clients — AIP180-C1 (enum value 제거 금지) |
일치 (간접) |
ca-tmpl 이 AIP-180 보다 약한 부분
- AIP-180 은 same major version 안에서 component 제거 사실상 영구 금지 (
C1). - ca-tmpl 은
migration window 90d/30d후 제거 허용 — internal-first skeleton 에 합리적 trade-off (Google 의 Stripe / public API 보다 운영 부담 낮음).
ca-tmpl 이 AIP-180 보다 강한 부분
- ca-tmpl:
migration window 90d/30d의무화 (AIP-180 은 사실상 무기한이라 명시적 window 없음). - ca-tmpl: CI breaking diff release-blocking (AIP-180 은 정책만 명시, 강제 메커니즘 별도).
Trade-off
- AIP-180 전면 도입: 사실상 영구 호환. Stripe 모델과 유사. 운영비용 큼.
- ca-tmpl: window 후 제거 허용. internal-first skeleton 에 합리적.
메모 / Notes
- AIP vs RFC vs Google internal: AIP 는 Google internal API design guideline 이지만 외부에 공개되어 reference 로 인용 가능. 정식 IETF/W3C 표준이 아님 — 외부 인용 시 "Google AIP" 로 명시, "공식 표준" 표현 금지.
- 재검증 완료: 2026-05-27 google.aip.dev WebFetch 재검증 성공 (5/5 verbatim). continuously updated 특성상 다음 검토 시 재확인 권장.
- 관련 AIP: AIP-181 (Stability levels), AIP-185 (Versioning) — 별도 raw 작성 후 통합 분석 권장.
Related / 관련
- 같은 주제 다른 official-doc / 표준:
- AIP-181 (Stability levels) — 별도 raw 작성 후보
- AIP-185 (Versioning) — 별도 raw 작성 후보
- 인용하는 branch:
- 인용하는 project:
- 인용한 wiki 요약: (미작성)