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:
+11
-2
@@ -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()) {
|
||||
|
||||
+3
-3
@@ -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 |
|
||||
""");
|
||||
|
||||
+7
-5
@@ -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`가 아니다");
|
||||
}
|
||||
}
|
||||
|
||||
+7
-4
@@ -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");
|
||||
|
||||
|
||||
+7
-7
@@ -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) {
|
||||
|
||||
+48
-9
@@ -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 {
|
||||
|
||||
Reference in New Issue
Block a user