Merge branch 'claude/d2c-ops-docs-1-c22c9f' — runbook·알림·JPA·관측·호환·storage 문서 번역

충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 92줄, D2c 67줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(128 → 61줄).
This commit is contained in:
DongHyeonka
2026-11-07 18:07:16 +09:00
83 changed files with 2266 additions and 2566 deletions
@@ -55,6 +55,13 @@ final class NotificationEvidenceVerifier {
/** A contract may extend a base; a longer chain is not followed. */
private static final int MAX_SUPERCLASS_DEPTH = 3;
/**
* The header of the column a table assigns grades in. The support matrix is written in Korean
* (docs/README.md), so its grade column is headed 등급; a table whose grade column is the first one
* lists what each grade requires and assigns nothing.
*/
private static final String GRADE_COLUMN_HEADER = "등급";
private static final Pattern SUPERCLASS =
Pattern.compile("\\bclass\\s+\\w+\\s+extends\\s+(\\w+)");
private static final Pattern PACKAGE = Pattern.compile("(?m)^package\\s+([\\w.]+)\\s*;");
@@ -117,7 +124,7 @@ final class NotificationEvidenceVerifier {
}
if (!insideTable) {
insideTable = true;
gradeColumn = cells.indexOf("Grade");
gradeColumn = cells.indexOf(GRADE_COLUMN_HEADER);
if (gradeColumn > 0) {
gradeAssigningTables++;
} else {
@@ -182,7 +189,9 @@ final class NotificationEvidenceVerifier {
throw new IllegalStateException(
"notification evidence: "
+ matrixFile.getName()
+ " has no table that assigns a grade (a 'Grade' column that is not the first"
+ " has no table that assigns a grade (a '"
+ GRADE_COLUMN_HEADER
+ "' column that is not the first"
+ " column), so no claim in it was checked.");
}
if (!problems.isEmpty()) {
@@ -150,7 +150,7 @@ class NotificationEvidenceVerifierTest {
Files.writeString(
fixture.matrix(),
"""
| Channel | Grade |
| 채널 | 등급 |
| --- | --- |
| email | Experimental |
""");
@@ -174,7 +174,7 @@ class NotificationEvidenceVerifierTest {
Files.writeString(
fixture.matrix(),
"""
| Grade | Requires |
| 등급 | 필요한 claim |
| --- | --- |
| Stable | delivery |
""");
@@ -248,7 +248,7 @@ class NotificationEvidenceVerifierTest {
Files.writeString(
matrix,
"""
| Channel | Grade |
| 채널 | 등급 |
| --- | --- |
| email | Stable |
""");
@@ -42,14 +42,16 @@ class NotificationReleaseGateTest {
// The terms must appear, but only under the refusal heading. Asserting they are absent
// altogether would be the wrong test: a matrix that never mentions guaranteed delivery leaves
// the reader to assume it, which is exactly the assumption this document exists to remove.
int refusalHeading = text.indexOf("## Not supported");
int refusalHeading = text.indexOf("## 지원하지 않는 것");
assertThat(refusalHeading).as("the matrix must state what it refuses to claim").isPositive();
String claims = text.substring(0, refusalHeading);
String refusals = text.substring(refusalHeading);
assertThat(claims).doesNotContain("guaranteed delivery", "guaranteed read", "exactly-once");
assertThat(refusals).contains("guaranteed delivery", "guaranteed read", "exactly-once");
assertThat(claims)
.doesNotContain(
"전달 보장", "읽음 보장", "정확히 한 번", "guaranteed delivery", "guaranteed read", "exactly-once");
assertThat(refusals).contains("전달 보장", "읽음 보장", "정확히 한 번");
assertThat(text).contains("PROVIDER_ACCEPTED", "AMBIGUOUS", "FCM_FID");
}
@@ -57,7 +59,7 @@ class NotificationReleaseGateTest {
void theEvidenceDocumentStatesTheForbiddenPromotions() throws IOException {
String text = Files.readString(DOCS.resolve("support-matrix.md"));
assertThat(text).contains("is not `DEVICE_DELIVERED`");
assertThat(text).contains("is not `DELIVERED`");
assertThat(text).contains("`DEVICE_DELIVERED`가 아니다");
assertThat(text).contains("`DELIVERED`가 아니다");
}
}
@@ -46,7 +46,7 @@ class PoolLaneClaimTest {
private static final String REMOVED_FLAG = "performance." + "assertions." + "enabled";
@Test
@DisplayName("no file describing the pool lane mentions the flag that was removed")
@DisplayName("풀 lane을 설명하는 파일은 지운 스위치를 말하지 않는다")
void noFileMentionsTheRemovedFlag() {
for (String description : LANE_DESCRIPTIONS) {
assertThat(read(description))
@@ -56,7 +56,7 @@ class PoolLaneClaimTest {
}
@Test
@DisplayName("no file describing the pool lane claims a certification or a machine bound")
@DisplayName("풀 lane을 설명하는 파일은 인증이나 기계 상한을 주장하지 않는다")
void noFileClaimsACertificationOrAMachineBound() {
for (String description : LANE_DESCRIPTIONS) {
String text = read(description).toLowerCase(Locale.ROOT);
@@ -68,12 +68,15 @@ class PoolLaneClaimTest {
.as("%s describes the pool lane as certifying something it does not measure", description)
.doesNotContain("pool pressure certification")
.doesNotContain("machine-dependent bounds")
.doesNotContain("machine bounds");
.doesNotContain("machine bounds")
.doesNotContain("풀 압력 인증")
.doesNotContain("기계 상한")
.doesNotContain("기계에 따라 다른 상한");
}
}
@Test
@DisplayName("the nightly job runs the behaviour lane, under its behaviour name")
@DisplayName("nightly job은 동작 lane을 그 동작 이름으로 돌린다")
void theNightlyJobRunsTheBehaviourLane() {
String nightly = read(".github/workflows/jpa-nightly.yml");
@@ -28,7 +28,7 @@ class JpaDocumentationContractTest {
private final JpaReleaseManifest manifest = JpaReleaseManifest.loadFromRepository();
@Test
@DisplayName("the support matrix names the registry's provider baseline, not the target")
@DisplayName("지원 매트릭스는 목표가 아니라 registry의 provider 기준선을 이름 댄다")
void theSupportMatrixNamesTheRegistrysProviderBaseline() {
String matrix = read("docs/jpa/support-matrix.md");
@@ -42,7 +42,7 @@ class JpaDocumentationContractTest {
}
@Test
@DisplayName("every gate the registry declares is named in the support matrix")
@DisplayName("registry가 선언한 gate는 모두 지원 매트릭스에 이름이 있다")
void everyRegistryGateIsNamedInTheSupportMatrix() {
String matrix = read("docs/jpa/support-matrix.md");
@@ -52,7 +52,7 @@ class JpaDocumentationContractTest {
}
@Test
@DisplayName("the H2 passage separates measurement from guarantee")
@DisplayName("H2 단락은 측정과 보장을 가른다")
void theH2PassageSeparatesMeasurementFromGuarantee() {
String matrix = read("docs/jpa/support-matrix.md");
@@ -62,18 +62,18 @@ class JpaDocumentationContractTest {
assertThat(flowed)
.as("two documents disagreed about SKIP LOCKED because they answered different questions")
.contains("not a production guarantee")
.contains("PostgreSQL contract evidence");
.contains("운영 보장이 아니")
.contains("PostgreSQL 계약 증거");
}
@Test
@DisplayName("the boundary document states the gap it does not enforce")
@DisplayName("경계 문서는 강제하지 않는 빈틈을 밝힌다")
void theBoundaryDocumentStatesItsGap() {
String adaptation = read("docs/jpa/repository-adaptation.md");
assertThat(adaptation)
.as("a document may call a boundary enforced only where a test actually enforces it")
.contains("Known gap");
.contains("알려진 빈틈");
}
private static String read(String repositoryRelativePath) {
@@ -35,11 +35,16 @@ import org.yaml.snakeyaml.Yaml;
* <li><b>LINK RESOLUTION</b> — every non-null {@code runbook_link} resolves to an existing file
* under {@code docs/runbooks/}.
* <li><b>PLACEHOLDER/STUB SMOKE</b> — runbook body must not contain TODO/TBD/PLACEHOLDER/FIXME
* and frontmatter must not have {@code status: stub} — EXCEPT files on the {@code
* LEGACY_STUB_DEBT} below. Files outside this temporary debt set that are stub/placeholder
* FAIL.
* and frontmatter must not have the draft status {@code status: 초안} — EXCEPT files on the
* {@code LEGACY_STUB_DEBT} below. Files outside this temporary debt set that are
* draft/placeholder FAIL.
* </ol>
*
* <p>A runbook's {@code status} is one of the two words the runbook template ({@code
* docs/runbooks/template.md}) allows: {@code 초안} (draft) or {@code 운영} (in operation). Any other
* value fails, so a stub written with the retired {@code stub} spelling cannot pass as a finished
* runbook.
*
* <p>The registry and runbook directory are checked-in contract resources. Missing resources and
* every contract violation are hard failures.
*
@@ -54,7 +59,7 @@ class RunbookCoverageContractTest {
* (feature-operational-runbook-contract D9).
*
* <p>These are only the legacy stub runbooks seeded during Phase D1. This set must exactly match
* the current {@code status: stub} files. Do not add new debt here: complete the runbook or adopt
* the current {@code status: 초안} files. Do not add new debt here: complete the runbook or adopt
* the future owned, expiring debt ledger.
*/
private static final Set<String> LEGACY_STUB_DEBT =
@@ -105,6 +110,12 @@ class RunbookCoverageContractTest {
"startup-required-adapter-disabled.md",
"startup-validation-failed.md");
/** The draft status: the runbook's body is not written yet. */
private static final String DRAFT_STATUS = "초안";
/** Every status a runbook may declare: draft, or in operation. */
private static final Set<String> RUNBOOK_STATUSES = Set.of(DRAFT_STATUS, "운영");
/** Categories exempt from mandatory-runbook requirement (client-error only). */
private static final Set<String> EXEMPT_CATEGORIES =
Set.of("VALIDATION", "NOT_FOUND", "CONFLICT", "DATA_INTEGRITY");
@@ -232,7 +243,7 @@ class RunbookCoverageContractTest {
}
Path trackedRunbook =
repositoryResources.requireTrackedFileInside("docs/runbooks", filename);
if (extractFrontmatterStatus(Files.readString(trackedRunbook)).equals("stub")) {
if (extractFrontmatterStatus(Files.readString(trackedRunbook)).equals(DRAFT_STATUS)) {
currentStubRunbooks.add(filename);
}
}
@@ -241,7 +252,7 @@ class RunbookCoverageContractTest {
assertThat(LEGACY_STUB_DEBT)
.as(
"LEGACY_STUB_DEBT is temporary containment and must match every and only current "
+ "status=stub runbook; do not add new allowlist entries—complete the runbook "
+ "status=초안 runbook; do not add new allowlist entries—complete the runbook "
+ "or adopt the future owned, expiring debt ledger")
.containsExactlyInAnyOrderElementsOf(currentStubRunbooks);
}
@@ -264,15 +275,15 @@ class RunbookCoverageContractTest {
Path trackedRunbook =
repositoryResources.requireTrackedFileInside("docs/runbooks", filename);
String content = Files.readString(trackedRunbook);
// Check for status: stub in frontmatter
boolean hasStubStatus = extractFrontmatterStatus(content).equals("stub");
// Check for the draft status in frontmatter
boolean hasStubStatus = extractFrontmatterStatus(content).equals(DRAFT_STATUS);
// Check for placeholder body text
boolean hasPlaceholderBody = PLACEHOLDER_PATTERN.matcher(content).find();
if (hasStubStatus || hasPlaceholderBody) {
violations.add(
filename
+ ": "
+ (hasStubStatus ? "status=stub" : "")
+ (hasStubStatus ? "status=초안" : "")
+ (hasPlaceholderBody ? " body-contains-placeholder" : ""));
}
}
@@ -285,6 +296,34 @@ class RunbookCoverageContractTest {
.isEmpty();
}
@Test
void everyRunbookFrontmatterDeclaresDraftOrOperatingStatus() throws Exception {
// given
List<String> outsideVocabulary = new ArrayList<>();
// when
try (Stream<Path> files = Files.list(runbooksDir)) {
for (Path path : files.sorted().toList()) {
String filename = path.getFileName().toString();
if (!filename.endsWith(".md") || filename.equals("template.md")) {
continue;
}
Path trackedRunbook =
repositoryResources.requireTrackedFileInside("docs/runbooks", filename);
String content = Files.readString(trackedRunbook);
String status = extractFrontmatterStatus(content);
if (!extractFrontmatter(content).isEmpty() && !RUNBOOK_STATUSES.contains(status)) {
outsideVocabulary.add(filename + ": status=" + status);
}
}
}
// then
assertThat(outsideVocabulary)
.as("A runbook's frontmatter status must be one of %s", RUNBOOK_STATUSES)
.isEmpty();
}
@Test
void runbookCoverageRejectsFrontmatterFromSymlinkOutsideRunbooks(@TempDir Path tempDir)
throws Exception {