docs(jpa): JPA 운영 문서를 한국어로 옮기고 코드와 맞춘다

문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.

고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
  gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
  `` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
  lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
  한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
  - support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
    `JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
  - repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
    `src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
    `composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
    plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
    `JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
    여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
  - experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
  증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
  고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.

버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.

위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:persistence-jpa:check` rc=0(666개 실패 0. `JpaDocumentationContractTest` 4,
  `JpaReleaseRenderingTest` 13, `PoolLaneClaimTest` 3), `:mainCheck` rc=0, `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `JpaDocumentationContractTest`의 H2 단락·알려진 빈틈 2개가 실패한다.
  `PoolLaneClaimTest`는 금지 문구를 더한 것이라 옛 영어 문서에서도 통과한다(RED 없음).
This commit is contained in:
DongHyeonka
2026-11-07 17:56:34 +09:00
parent 5a860e1e6b
commit b1cda0307b
16 changed files with 700 additions and 873 deletions
@@ -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) {