문제: main job은 `./gradlew :mainCheck :integrationCheck --continue` 한 번이다. integration lane은 build 전체에서 실서버 슬롯 하나를 나눠 쓴다 (ExclusiveRealServerLaneService, maxParallelUsages 1). desktop 측정에서 이 lane들은 시작 약 10분 동안 슬롯을 거의 쓰지 못했다. main 단계 분석이 CPU를 다 쓰는 동안 lane의 컴파일이 뒤로 밀렸기 때문이다. 그 뒤 19분은 lane이 한 번에 하나씩, 한가한 기계에서 돌았다. runner run 132에서도 jpa 계약 lane이 1,134초에야 시작했다. 고른 방법: 줄을 `./gradlew :integrationCheck :mainCheck --continue`로 바꾼다. Gradle은 준비된 일을 요청한 태스크 순서대로 시작하므로, integration lane의 컴파일이 먼저 돌고 슬롯이 첫 분부터 찬다. 같은 단계, 같은 태스크 집합이다. build.gradle 단계 선언의 `line`, main.yml, scripts/verify.sh, gates.md, build-logic/AGENTS.md의 예시 줄을 함께 바꾼다. 측정(desktop,e7be517e, --no-build-cache, 같은 init script): - 순서 바꾸기 전 1,760초(aeb60339, 거의 같은 트리), 바꾼 뒤 1,484초(−16%), rc=0, 실패 0 - jpa 계약 lane 시작 777초 → 329초. 슬롯이 60초부터 끝까지 찬다. 버린 대안: 슬롯을 둘로 늘리기. 시간에 민감한 web·WebSocket lane이 함께 돌 때 실패해서 하나로 둔 것이다(2026-11-01 리뷰). lane을 두 Gradle 실행으로 나누기: 컴파일을 두 번 한다. 위험·한계: lane이 main 단계 분석과 같은 시간에 돌아 CPU를 나눠 쓴다. 지금도 앞 10분에는 전송 qualification lane이 그렇게 돌았다. desktop 한 번은 실패 0이고, runner 결과는 PR 본문에 적는다. 이제 main job 시간은 슬롯 lane 시간의 합이 정한다(가장 큰 것은 PostgreSQL 컨테이너 기동, 후속).
35 lines
5.5 KiB
Markdown
35 lines
5.5 KiB
Markdown
# build-logic — Gradle 정책 권위
|
|
|
|
registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. `build-logic/`, `settings.gradle`, `build.gradle`, `gradle/modules.json`을 고칠 때 읽는다. 루트 `AGENTS.md` HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 `docs/work/reference/gates.md`다.
|
|
|
|
## 정본 넷
|
|
|
|
- `gradle/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 `library_groups`, 행마다 `allowed_libraries`. 계층 leaf 행은 비워 둔다. 설명은 `gradle/README.md`). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
|
|
- `settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
|
|
- `build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.
|
|
- `build.gradle`: 루트 라이프사이클(`ci`, `prCheck`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 그것을 workflow job에 묶는 `strictLaneStages`, 버전·리비전.
|
|
|
|
## 저장소 파일을 읽는 테스트
|
|
|
|
- 테스트가 저장소 파일을 읽으면 그 파일을 그 leaf의 test task `inputs`로 선언한다.
|
|
- 저장소 문서와 대조하는 테스트는 `mainStage()` 레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다.
|
|
- 문서가 아닌 저장소 파일(빌드 스크립트, workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔 별도 레인(app-bootstrap `repository-contract`)에 둔다.
|
|
- 저장소 루트(`ca.repository.root`)는 이 두 레인에만 준다. 그래서 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다.
|
|
- 문서를 파싱해 대조하는 Gradle 검사는 두지 않는다. 문서 검사는 Gradle 밖 `scripts/check-docs.py`·`scripts/check-work-docs.py`다.
|
|
|
|
## lane 캐시와 성능 lane
|
|
|
|
- `TEST`·`ARCHITECTURE` lane은 입력이 같으면 up-to-date·build cache를 쓴다. `INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼 입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을 입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.
|
|
- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다. convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
|
|
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 `ca.config-contract`다.
|
|
|
|
## 단계 job의 모양
|
|
|
|
- `verifyStrictLaneStages --dry-run`(PR)은 `explicitOnly`가 아닌 strict lane마다 `build.gradle`의 `strictLaneStages`가 선언한 단계 태스크 하나의 계획에 들어 있는지 본다(그래프 검사).
|
|
- 단계마다 선언한 workflow job은 step의 `run: ./gradlew <단계> <옵션>` 줄을 가지고(같은 job을 쓰는 단계는 선언한 `line`대로 한 줄을 나눠 쓸 수 있다: `./gradlew :integrationCheck :mainCheck --continue`), 다른 step `run:`도 셸 문법 없는 `./gradlew` 한 줄이나 `bash scripts/<이름>.sh` 한 줄이며, 선언 밖의 `if:`, 선언한 조건이 `!cancelled()`·`always()`가 아닌데 `needs:`, `continue-on-error`·`shell:`·`defaults:`, 따옴표 키·flow 형식, 이 빌드 밖의 `working-directory`가 없다. workflow는 선언한 이벤트로, 선언한 필터 한 줄만 달고 시작하고, PR 단계 job 하나가 이 검사를 돌린다(형식 검사, 셸을 해석하지 않는다).
|
|
- 단계를 더하거나 job을 바꾸면 `strictLaneStages`의 `stage` 줄과 workflow를 같은 커밋에서 고친다.
|
|
|
|
## 테스트
|
|
|
|
- `./gradlew -p build-logic test --console=plain`(저장소 루트에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다.
|