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:
+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) {
|
||||
|
||||
Reference in New Issue
Block a user