Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

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 = breaking
- AIP180-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 작성 후 통합 분석 권장.

같은 주제 다른 official-doc / 표준:
- AIP-181 (Stability levels) — 별도 raw 작성 후보
- AIP-185 (Versioning) — 별도 raw 작성 후보
인용하는 branch:
- raw/branch-notes/feature-api-compatibility-deprecation-contract
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract
인용한 wiki 요약: (미작성)

10 KiB Raw Permalink Blame History