ci(docs)!: 문서 검사가 registry YAML이 가리키는 경로도 본다
pr / done (pull_request) Successful in 2m29s

문제: 코드 파일을 옮기는 PR은 docs/registries/*.yaml 행의 source·
registered_by가 옛 경로로 남아도 초록이다. scripts/check-docs.py의 reference
검사는 마크다운만 읽고, 행과 코드를 대조하는 MetricsRegistryCodeAlignmentTest·
HeaderRegistryRuntimeAlignmentTest는 main 단계에서만 돈다. #38이 이렇게
병합돼 main이 빨강이 됐고, main이 빨강인 동안 다른 PR 병합이 모두 멈췄다.

방법: reference 검사가 docs/registries/*.yaml의 줄에서 repo 경로 모양의 낱말
(PATH_ROOTS로 시작, 공백·따옴표·한글에서 끊는다)을 찾아 git이 아는 파일인지
본다. headers.yaml의 "service: src/..." 같은 접두어 붙은 값과 주석의 경로도
같은 규칙으로 잡는다. gates.md 2절에 「지표·헤더를 등록하는 코드를 옮기거나
바꿈 → :app-bootstrap:documentContractTest」 행을 따로 두고, 「지우거나 옮김」
행에 registry YAML을 적는다. docs/README.md 「문서 검사」 표와 관측 업그레이드
안내(14번 행)를 고친다.
버린 대안: (1) 대조 시험을 PR 단계로 옮기기 — 문서 대조는 main 단계라는
결정(2026-09-16)을 바꾸고 Gradle lane 하나를 PR에 더한다. (2) gates.md에
사람이 돌릴 lane만 적기 — #38도 그 표를 따랐어야 했지만 기계가 막지 않으면
다시 샌다.

PR 단계에 두는 이유(gates.md 7절 5번): 이미 PR에서 도는 check-docs.py의
기존 검사가 볼 파일만 넓힌다. 새 태스크·job이 없고 Gradle 없이 1초 안에
끝난다. 옮기는 PR에서 잡지 못하면 main이 빨강이 되어 모든 병합이 멈춘다.

위험·한계: 경로가 있는지만 본다. 파일은 남고 등록 줄만 다른 파일로 옮긴
경우는 여전히 main 단계 document-contract lane이 잡는다(gates.md 새 행).
파생 서비스는 registry 주석에 적은 경로가 없으면 PR에서 새로 실패한다. 주석은
지금까지 어떤 검사도 보지 않았다. source·registered_by는 main 단계 대조
시험에서 이미 실패하던 경로다.

검증: 노트북 `bash scripts/verify.sh docs` rc=0(스크립트 시험 170개 통과).
옛 metrics.yaml에서 `check-docs.py --only reference`가 rc=1로
metrics.yaml:878을 가리킨다. 새 시험 셋은 옛 check-docs.py에서 실패하고, 정규식
변이 셋(따옴표 안 값만 보기, 한글에서 안 끊기, 주석 건너뛰기)이 각각 시험
하나 이상을 실패시킨다.

BREAKING CHANGE: docs/registries/*.yaml의 값과 주석에 적은 repo 경로가 지금
트리에 없으면 PR 단계 documentCheck가 실패한다. 파생 서비스는
`python3 scripts/check-docs.py --only reference`로 자기 행·주석을 확인한다
(docs/upgrade/2026-11-round9-observability.md 14번).
This commit is contained in:
DongHyeonka
2026-11-18 21:17:34 +09:00
parent b43fd78c23
commit a00d559c84
5 changed files with 50 additions and 4 deletions
+1 -1
View File
@@ -192,7 +192,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
| --- | --- |
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. `docs/registries/*.yaml`은 값과 주석에 적은 repo 경로를 본다(행의 `source`·`registered_by`가 옮긴 파일을 가리키면 PR에서 걸린다). 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
+3 -1
View File
@@ -1,7 +1,8 @@
# 업그레이드 안내 — 2026-11 관측 registry·로그 내용·로컬 비밀 기본값
- 범위: 2026-11-12 전체 리뷰의 관측 registry 묶음, 로그 내용 묶음, 비밀·IP 문서 묶음을 고친 변경. 지표·MDC·헤더 registry를 코드에
맞췄고, 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했고, 로컬 비밀 기본값을 `__LOCAL_DEV_` 규칙에 맞췄다.
맞췄고, 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했고, 로컬 비밀 기본값을 `__LOCAL_DEV_` 규칙에 맞췄다. 2026-11-18에
registry가 가리키는 경로를 PR에서 보는 문서 검사를 더했다(14번).
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-05·07·08·09·10·12·13·15·21·22·26·27,
RR9-03-05
@@ -27,6 +28,7 @@ compose로 개발하는 사람이다.
| 11 | 단일 인스턴스(in-process) lock도 `lock.acquisition`을 센다 | 단일 인스턴스 배포의 lock 경보 기준선을 다시 잡는다 | 새로 생긴 값으로 경보가 울릴 수 있다 | persistence-jpa를 켠 서비스 |
| 12 | `docs/registries/mdc-keys.yaml`은 코드가 MDC에 넣는 다섯 key(`request_id`, `trace_id`, `span_id`, `correlation_id`, `user_principal`)만 적는다. `headers.yaml`에서 아무도 쓰지 않던 `Deprecation`·`Sunset`을 지우고 쓰는 헤더 행을 더했다(`tracestate`는 W3C 전파가 쓰므로 `framework:` 행으로 둔다). 지표·헤더 행마다 `source`가 있다 | 자기 MDC key·헤더·지표를 더한 서비스는 `MdcKeys`·행을 같이 더하고 `source`를 적는다 | 새 정합 시험이 실패한다 | registry에 행을 더한 서비스 |
| 13 | testFixtures `CardinalityBounds`: `STATUS_CODE`가 7에서 40(숫자 HTTP status)으로, `RESILIENCE4J_OUTCOME`(5)이 `OUTCOME`(6)으로 바뀌었고 `uri` key가 더해졌다. `MetricNaming.ALLOWED_UNITS`는 이름 접미사가 아니라 `unit` 칸의 값이다 | 그 상수를 쓰던 시험을 새 이름·값으로 고친다 | 시험 컴파일이 실패한다 | 그 fixture를 쓰는 서비스 |
| 14 | `scripts/check-docs.py`의 `reference` 검사가 `docs/registries/*.yaml`의 값과 주석에 적은 repo 경로(`src/`·`docs/`·`scripts/` 등으로 시작하는 것)도 본다. 행의 `source`·`registered_by`가 옮기거나 지운 파일을 가리키면 PR 단계에서 걸린다(전에는 main 단계의 대조 시험만 `source`·`registered_by`를 봤고 주석은 아무도 보지 않았다) | `python3 scripts/check-docs.py --only reference`로 자기 registry 행과 주석의 경로가 지금 트리에 있는지 본다. 코드를 옮기는 변경에서 그 행도 고친다 | PR 단계 `documentCheck`가 「없는 경로다」로 실패한다 | registry에 행이나 주석을 더한 서비스 |
## 3. 바뀌지 않은 것
+2 -1
View File
@@ -64,7 +64,8 @@ workflow에만 있는 job: `pr.yml` `done`의 마지막 step과 `main.yml`의 `v
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` |
| 의존성 | `verifyDependencyLocks` |
| 문서(`docs/**`, `AGENTS.md`·`CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` |
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) |
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서와 `docs/registries/*.yaml`이 가리키던 경로가 사라진다) |
| 지표·헤더를 등록하는 코드(이름 상수, 등록 줄, 그 파일)를 옮기거나 바꿈 | `:app-bootstrap:documentContractTest`(registry 행과 등록 코드를 대조한다. 파일은 남고 등록만 다른 파일로 간 행은 이 lane만 본다) |
| `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` |
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
| build-logic·workflow(`.gitea/`) | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` |