82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
---
|
|
title: blog-topic / runbook-coverage-junit-contract-test
|
|
source_type: blog-topic
|
|
status: raw
|
|
related_branches: [feature-operational-runbook-contract]
|
|
related_projects: [ca-tmpl]
|
|
tags: [blog-topic, ca-tmpl, observability, testing, junit5, api-contract]
|
|
created: 2026-07-02
|
|
status_label: ready-for-canonical
|
|
target_audience: backend-engineer
|
|
inspiration_url:
|
|
archive_url:
|
|
---
|
|
|
|
# blog-topic: runbook-coverage-junit-contract-test
|
|
|
|
> Layer: `raw/blog-topics/` — 작업 중 나온 블로그 글감 원석. 최종 블로그는 canonical 정제 후 `wiki/blog/`에서 작성한다.
|
|
|
|
## Parent / 부모
|
|
|
|
- [[raw/branch-notes/feature-operational-runbook-contract]] — 운영 runbook coverage gate를 테스트로 구현한 경험에서 나온 글감.
|
|
|
|
## 트리거 / Trigger
|
|
|
|
- 트리거 유형: `branch-work`
|
|
- 트리거 날짜: 2026-07-02
|
|
- 트리거 연결 노트: [[raw/branch-notes/feature-operational-runbook-contract]]
|
|
|
|
## 글감 / Topic seed
|
|
|
|
- 한 문장 요지: 운영 runbook 링크가 문서에만 존재하는지, 실제 error registry와 연결되어 release를 막을 수 있는지 JUnit contract test로 확인한 이유를 정리한다.
|
|
- 예상 제목 후보:
|
|
- Runbook coverage를 JUnit 테스트로 막아본 이유
|
|
- 운영 문서도 release gate가 될 수 있을까
|
|
|
|
## 핵심 주장 후보 / Claim candidates
|
|
|
|
- 사실 후보:
|
|
- branch에 runbook coverage gate와 link-check smoke가 구현/검증된 것으로 정리되어 있고 blog topic 후보가 Cluster에 명시되어 있다 — 근거 후보: [[raw/branch-notes/feature-operational-runbook-contract]] line `:301`.
|
|
- 경험 후보:
|
|
- Gradle task가 아니라 test suite에 넣는 방식은 release-blocking semantics를 명확히 하는 장점이 있다.
|
|
- 의견/해석 후보:
|
|
- runbook은 "있으면 좋은 문서"가 아니라 retryable failure와 연결될 때 운영 계약이 된다.
|
|
|
|
## Outline seed
|
|
|
|
1. error code와 runbook을 따로 관리하면 drift가 생긴다 — registry row와 문서 링크를 같은 gate로 본다.
|
|
2. JUnit으로 문서 coverage를 검사하는 이유 — application test lifecycle에 운영 artifact를 포함한다.
|
|
3. link-check와 semantic coverage는 다르다 — URL이 살아 있어도 runbook이 충분하다는 뜻은 아니다.
|
|
|
|
## Canonical 전환 후보 / Canonical extraction candidates
|
|
|
|
- `wiki/projects/ca-tmpl/operational-runbook-coverage-gate.md` 후보:
|
|
- ca-tmpl runbook coverage gate 구현 사실.
|
|
- `wiki/concepts/runbook-coverage-gate.md` 후보:
|
|
- error registry와 runbook coverage를 연결하는 일반 패턴.
|
|
- 필요한 추가 검증:
|
|
- 테스트명, registry schema, retryable=true row 처리 방식.
|
|
|
|
## Sources / 근거 후보
|
|
|
|
- [[raw/branch-notes/feature-operational-runbook-contract]] — runbook coverage gate topic seed와 구현/검증 근거.
|
|
|
|
## 미해결 / Unknown
|
|
|
|
- 아직 확인해야 할 사실: link-check smoke와 coverage gate의 정확한 차이.
|
|
- 과장하면 안 되는 부분: runbook 내용 품질까지 자동 보장한다고 쓰면 안 된다. coverage와 link existence 검증으로 제한한다.
|
|
- 블로그로 쓰기 전에 필요한 canonical 정제: runbook coverage gate project 문서 생성 또는 observability 문서 통합.
|
|
|
|
## Decision / 처리 결정
|
|
|
|
- 액션: `promote-to-canonical`
|
|
- 이유: `wiki/projects/ca-tmpl/observability-log-metric-trace-runbook.md` 에 runbook coverage JUnit contract test 글감으로 반영했다.
|
|
- 다음 단계: source canonical이 `verified` 상태이므로 이후 `blogify` 대상으로 삼을 수 있다. 단 runbook 내용 품질까지 자동 보장한다고 쓰지 않는다.
|
|
|
|
## Related / 관련
|
|
|
|
- 관련 branch: [[raw/branch-notes/feature-operational-runbook-contract]]
|
|
- 관련 error:
|
|
- 관련 interview prep:
|
|
- derived blog: 생성 전. 생성 시 `wiki/blog/runbook-coverage-junit-contract-test-YYYY-MM-DD.md` 후보
|