docs(ci): 단계·job 설명과 링크 검사 범위를 지금 workflow에 맞춘다 #18

Merged
donghyeon.kang merged 2 commits from claude/w2-be-ci-perf-3 into main 2026-11-12 16:59:59 +00:00
8 changed files with 19 additions and 13 deletions
+1 -1
View File
@@ -98,7 +98,7 @@ jobs:
README.md
docs/build.md
'src/**/README.md'
'src/**/CLAUDE.md'
'src/**/AGENTS.md'
'docs/**/*.md'
'.github/**/*.md'
fail: true
+5
View File
@@ -30,6 +30,11 @@ env:
jobs:
# The tag-only checks: release provenance and the public path baseline. Not `ci` again: a tag is
# cut from a main commit the pull-request and main stages already ran on.
#
# The jobs after this one do run again some tests `ci` ran (the web, WebSocket and HTTP client
# suites, the fileserver checks, three persistence-jpa tests). They are the release evidence the
# support documents name by job id, and the image job needs every one of them, so each of them
# passed in this run on this commit before anything is published.
release:
runs-on: ubuntu-latest
timeout-minutes: 30
+5 -4
View File
@@ -8,7 +8,7 @@ plugins {
// plugin reachable from two classpaths is two versions waiting to differ. Their versions are the
// same catalog entries either way — build-logic/settings.gradle reads gradle/libs.versions.toml.
alias(libs.plugins.spring.boot) apply false
// JMH benchmarks in three leaves (`./gradlew :<leaf>:jmh`); never part of a gate.
// JMH benchmarks in the leaves that apply this plugin (`./gradlew :<leaf>:jmh`); never part of a gate.
alias(libs.plugins.jmh) apply false
// Convention plugin from the included build, applied to the ROOT because the rules it owns are
@@ -145,9 +145,10 @@ tasks.register('testQualityCheck') {
}
// The feature generator's round trip (review 2026-11-01 개선 순서 4): scripts/new-feature.sh writes
// two features into a throwaway copy of the working tree and that copy's own Gradle runs the leaf
// checks they touch plus architectureCheck. A nested build of five leaves, so the main stage, not
// the pull request. The script is the whole check; this task only gives it a stage.
// two features into a throwaway copy of the working tree and that copy's own Gradle runs the checks
// of the five leaves they touch plus architectureCheck, which runs every leaf's architecture lane. A
// nested build that long belongs to the main stage, not the pull request. The script is the whole
// check; this task only gives it a stage.
tasks.register('verifyFeatureScaffold', Exec) {
group = 'verification'
description = 'Generates features with scripts/new-feature.sh in a scratch copy and runs the gates they must pass.'
+2 -2
View File
@@ -17,7 +17,7 @@
| 대상 | 무엇을 지키는가 |
| --- | --- |
| `docs/design/**`, `docs/history/**` | 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록 |
| `main.yml`의 nightly job(`jpa-postgresql`, `httpclient-transport`, `redis-topology`, `fileserver-nfs-ambiguity`, `notification-chaos`, `jpa-next`, `object-storage-aws`)과 `release.yml`의 영역별 release lane | 템플릿이 광고하는 지원 매트릭스의 근거. 서비스가 그 capability를 쓰면 남기고, 지운 capability의 job은 같이 지운다 |
| `main.yml`의 nightly job(`jpa-postgresql`, `httpclient-transport`, `redis-topology`, `fileserver-nfs-ambiguity`, `notification-chaos`, `jpa-next`), 손으로 실행할 때 입력 `run_protected_aws`를 켜야만 도는 `object-storage-aws`, `release.yml`의 영역별 release lane | 템플릿이 광고하는 지원 매트릭스의 근거. 서비스가 그 capability를 쓰면 남기고, 지운 capability의 job은 같이 지운다 |
## Consumer 필수 (파생 프로젝트가 유지해야 한다)
@@ -37,7 +37,7 @@
| `prCheck`의 `verifyWorkDocs` | 작업 지침의 분량 상한·본문 이력 ID 0·playbook 뼈대(`scripts/check-work-docs.py`). 파생 서비스도 `docs/work/`와 `AGENTS.md`를 받으니 같은 상한을 지킨다 |
| `prCheck`의 `documentCheck`·`testDocumentChecks` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) |
| `main.yml`의 `links` job | 문서의 외부 URL과 상대 링크(lychee) |
| `scripts/check-repo-layout.py`(`prCheck`의 `verifyRepositoryLayout`) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 |
| `scripts/check-repo-layout.py`(`prCheck`의 `verifyRepositoryLayout`) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 이 스크립트의 허용 목록을 고친다. `src/` 최상위 폴더면 `AGENTS.md` 지도의 `src/` 줄도 같은 변경에서 고친다(루트 항목은 지도에 목록이 없고 이 스크립트를 가리킨다) |
| action의 전체 URL·full SHA 핀 | 공급망 |
## 파생 프로젝트가 할 일
+2 -2
View File
@@ -84,7 +84,7 @@ workflow에만 있는 job: `pr.yml` `done`의 마지막 step과 `main.yml`의 `v
- 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew <gradle-path>:resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다.
- 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다.
**링크 검사**: 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL까지 보는 lychee는 문서 검사라 main 단계다(`main.yml` `links`, 범위 `README.md`, `docs/build.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`). 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다).
**링크 검사**: 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL까지 보는 lychee는 문서 검사라 main 단계다(`main.yml` `links`, 범위 `README.md`, `docs/build.md`, `src/**/README.md`, `src/**/AGENTS.md`, `docs/**/*.md`, `.github/**/*.md`. 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이라 링크가 없다). 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다).
## 3. 라운드 끝 — 합친 트리의 전체 묶음
@@ -113,7 +113,7 @@ workflow에만 있는 job: `pr.yml` `done`의 마지막 step과 `main.yml`의 `v
1. 바뀐 파일 목록을 만든다: `git diff --name-only <기준 커밋> <합친 커밋>`.
2. 바뀐 영역의 job을 고른다: PostgreSQL major(`jpa-postgresql`, persistence-jpa), HTTP transport(`httpclient-transport`, httpclient), Redis topology(`redis-topology`, redis leaf 셋), NFS(`fileserver-nfs-ambiguity`, fileserver), 알림 chaos(`notification-chaos`), 릴리스 lane(`release.yml`의 같은 영역 job).
3. 그 job의 `run` 줄을 저장소 루트에서 그대로 돌린다. 행렬은 값마다 한 번이다. `redis-topology`는 행렬이 아니라 행마다 step 하나이고, 그 `scripts/ci/redis-topology.sh <topology> <version>` 줄은 desktop에서도 같은 줄로 돈다.
3. 그 job의 `run` 줄을 저장소 루트에서 그대로 돌린다. 행렬은 값마다 한 번이다. `redis-topology`는 행렬이 아니라 행마다 step 하나이고, 그 `scripts/ci/redis-topology.sh <topology> <version>` 줄은 desktop에서도 같은 줄로 돈다. desktop에서는 앞에 `GRADLE_OPTS=-Dorg.gradle.daemon=false`를 붙인다(스크립트 안의 `./gradlew`가 daemon을 남기지 않게. CI는 step 사이에 daemon을 다시 쓴다).
4. 고르지 않은 job은 이름과 "바뀐 영역 아님"을 결과 표에 적는다.
5. 처음 켠 job이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 job을 돌림), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다.
+1 -1
View File
@@ -6,7 +6,7 @@
# 단계 무엇 workflow
# docs 문서·지침 검사와 스크립트 시험(Gradle 없음) pr.yml의 prCheck 안
# leaf <경로> registry gradle_path 하나의 check (작업 중)
# pr :prCheck, :verifyStrictLaneStages --dry-run pr.yml `gradle`
# pr :prCheck, :verifyStrictLaneStages --dry-run pr.yml `done`
# main :mainCheck, :integrationCheck, build-logic 시험, 설정 캐시 main.yml(push)
# nightly compose smoke 전부, :performanceCheck(마지막) main.yml(nightly)
# release :releaseCheck(이 커밋을 provenance로) release.yml `release`
@@ -91,9 +91,9 @@ leaf마다 자기 시험이 검증하는 lane을 가지고, lane마다 돌아야
| lane | `redis-runtime` | `redis-sdk` | `cache-redis` |
| --- | --- | --- | --- |
| standalone | `LiveRedisCompositionTest` | `RedisTopologyContractTest`, `LiveRedisGuardrailTest` | `LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest` |
| standalone | `LiveRedisCompositionTest` | `RedisTopologyContractTest`, `LiveRedisGuardrailTest` | `LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`, `LiveRedisDistributedLeaseContractTest`, `LiveRedisCacheRegionContractTest`, `LiveRedisIdempotencyStoreContractTest` |
| sentinel | `LiveRedisCompositionTest` | `RedisTopologyContractTest`, `LiveRedisSentinelPromotionTest` | — |
| cluster | `LiveRedisCompositionTest` | `LiveRedisClusterTest`, `LiveRedisClusterTransactionTest` | `LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest` |
| cluster | `LiveRedisCompositionTest` | `LiveRedisClusterTest`, `LiveRedisClusterTransactionTest` | `LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`, `LiveRedisDistributedLeaseContractTest`, `LiveRedisCacheRegionContractTest`, `LiveRedisIdempotencyStoreContractTest` |
| tls | `LiveRedisTlsTest` | — | — |
lane은 `docker compose -f src/adapter/outbound/redis-sdk/compose/<lane>/compose.yml down -v`로 내린다.
@@ -181,7 +181,7 @@ class DeveloperExperienceContractTest {
"README.md",
"docs/build.md",
"src/**/README.md",
"src/**/CLAUDE.md",
"src/**/AGENTS.md",
"docs/**/*.md",
".github/**/*.md");
}