옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.
- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
(Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
않았다.
검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.
Refs: design-docs repo-structure/05-library-repos.md 14.2절
This commit is contained in:
@@ -0,0 +1,41 @@
|
||||
# 작업 방법 — messaging-library를 고칠 때
|
||||
|
||||
이 repo에서 일을 맡은 사람과 에이전트가 먼저 읽는다. 루트 `AGENTS.md`의 「꼭 지킬 것」이 이 문서보다 먼저다.
|
||||
|
||||
## 1. 일의 종류와 읽을 곳
|
||||
|
||||
| 일 | 먼저 읽을 곳 | 끝났다는 증거 |
|
||||
| --- | --- | --- |
|
||||
| 모듈 코드 고치기·기능 더하기 | `messaging/AGENTS.md`(family 규칙, 공개 표면 정책), 관련 제품 문서(`docs/messaging/`) | 바꾼 모듈 `check` + `ci`(2절) |
|
||||
| Kafka adapter·전달 보장 바꾸기 | `messaging/AGENTS.md` 「Stable 승격에 필요한 증거」, `docs/messaging/support-matrix.md` | 위 + `mainCheck`(인증 lane과 증거 게이트) |
|
||||
| outbox·inbox·admin journal, migration | `docs/messaging/outbox-inbox.md` | 위 + `integrationCheck`. 적용된 migration은 고치지 않고 새 버전 파일을 더한다 |
|
||||
| 공개 타입·설정 키(`app.messaging.*`) 바꾸기 | `release.md` 2절 | `CHANGELOG.md`에 옮기는 법, 템플릿 쪽 영향 확인(3절) |
|
||||
| 빌드 규칙(build-logic) 고치기 | `build-logic/AGENTS.md`, `build-logic/UPSTREAM.md` | `buildLogicTest`(`ci` 안) |
|
||||
| 릴리스 | `release.md` | release.yml 초록, 익명 메타데이터에 새 버전 |
|
||||
| 리뷰 | 아래 2절의 게이트 목록과 루트 `AGENTS.md` 「꼭 지킬 것」 | 발견마다 위치·재현·고칠 곳 |
|
||||
|
||||
## 2. 검증
|
||||
|
||||
- 진입점은 `scripts/verify.sh <단계>`다. 소유자 환경에서는 Gradle·Docker를 desktop에서만 돌린다: `--on desktop`을 붙이면 지금 작업 트리를 패치로 옮겨 잠금(`/tmp/claude-gates/heavy.lock`) 아래에서 돌린다.
|
||||
- 무엇을 돌릴지는 `gates.md`다. 완료를 말하기 전에 바꾼 것에 맞는 게이트를 돌리고, 못 돌렸으면 이유를 적는다.
|
||||
|
||||
## 3. 백엔드 템플릿과 같이 고치기
|
||||
|
||||
백엔드 템플릿은 이 라이브러리를 버전으로 받는다(카탈로그 칸 `messagingLibrary`, 쓰는 곳은 `adapter:outbound:messaging`, `adapter:outbound:messaging-kafka`, `adapter:inbound:messaging`, `adapter:outbound:persistence-jpa`의 migration 시험, `composition:outbox-relay`의 시험). 템플릿 쪽 절차는 템플릿 `docs/work/reference/related-repos.md`다.
|
||||
|
||||
1. 이 repo와 템플릿에 브랜치를 하나씩 만든다. 두 repo를 같은 부모 폴더에 둔다.
|
||||
2. 템플릿 `src/`에서 명령 줄로만 이 repo를 끼운다. 파일은 바꾸지 않는다.
|
||||
|
||||
```bash
|
||||
./gradlew --include-build ../../messaging-library <태스크>
|
||||
```
|
||||
|
||||
3. 그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다.
|
||||
4. 병합 순서는 하나다: 이 repo PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. 끼운 상태로만 통과하는 템플릿 PR은 병합하지 않는다.
|
||||
5. 공개 API·설정 키·migration을 바꾸는 PR은 본문에 템플릿 쪽 영향(끼운 상태로 돌린 태스크와 결과)을 적는다.
|
||||
|
||||
## 4. 이 repo에서 정한 것
|
||||
|
||||
- 결정 기록은 `docs/adr/`에 쌓는다. 템플릿에서 옮겨 온 결정 기록은 없다(메시징 결정은 설계서와 템플릿 리뷰에 있다). 새 결정은 `docs/adr/0000-template.md` 양식으로 `ADR-MSG-001`부터 쓴다.
|
||||
- 문서는 한국어로 쓴다. 지난 결정을 고칠 때는 본문이 아니라 머리 블록의 「상태」·「현재 정본」만 고친다(`docs/README.md` 2절).
|
||||
- 커밋·PR 규칙은 design-docs `conventions/commit-and-pr.md`다. `main`에는 PR로 넣는다(첫 배포 전 첫 커밋들만 예외였다).
|
||||
@@ -0,0 +1,33 @@
|
||||
# 게이트 — 무엇을 언제 돌리나
|
||||
|
||||
단계 태스크는 루트 `build.gradle`이 정한다. workflow는 단계마다 Gradle 한 줄이고, 어떤 모듈·lane·검사가 들어가는지는 workflow가 아니라 Gradle이 정한다.
|
||||
|
||||
## 1. 단계
|
||||
|
||||
| 단계 | 언제 | 명령(`scripts/verify.sh`) | 들어 있는 것 |
|
||||
| --- | --- | --- | --- |
|
||||
| `ci` | PR(`pr.yml`) | `pr` | 모듈 `check` 전부(단위 시험, Spotless, Checkstyle, Error Prone, `messaging-testkit`의 저장소 계약 lane), SpotBugs(main·test), lockfile, `architectureCheck`, build-logic 시험. 그리고 `verifyStrictLaneStages --dry-run` |
|
||||
| `mainCheck` | main push·매일 03:30 KST(`main.yml`) | `main` | `ci` + `integrationCheck`(Testcontainers Kafka·Toxiproxy·PostgreSQL) + 브로커 인증 증거 게이트 `verifyMessagingCertificationEvidence` |
|
||||
| `releaseCheck` | `vX.Y.Z` 태그(`release.yml`) | `release` | 버전 확인, hermetic lane(`testLaneCheck`), `integrationCheck`, 인증 증거 게이트, SBOM, 의존성 취약점 검사 |
|
||||
| `release` | `vX.Y.Z` 태그 | — | `releaseCheck` 뒤 Gitea Packages에 서명해 올리고 익명으로 다시 읽는다 |
|
||||
| `releaseRehearsal` | 손으로 | `release` | `releaseCheck` 뒤 `build/staging-repository`에 올리고 파일마다 확인. 비밀 값 없이 돈다 |
|
||||
|
||||
성능 lane은 없다. `messaging-kafka`·`messaging-testkit`의 JMH 벤치마크(`./gradlew :messaging:<모듈>:jmh`)는 게이트가 아니다.
|
||||
|
||||
## 2. 바꾼 것에 맞는 게이트
|
||||
|
||||
| 바꾼 것 | 최소로 돌릴 것 |
|
||||
| --- | --- |
|
||||
| 모듈 하나의 코드 | `./gradlew <gradle path>:check`(path는 registry), 끝나기 전에 `scripts/verify.sh pr` |
|
||||
| `messaging-kafka`, 전달 보장·실패 분류 | 위 + `./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence`(Docker). 시나리오가 바뀌면 만들어진 `build/messaging-certification/broker-certification-evidence.jsonl`을 `messaging-testkit/src/main/resources/messaging/`에 덮어 같은 변경에 넣는다 |
|
||||
| `messaging-reliability*`, migration, starter 조립 | 위 + `./gradlew integrationCheck`(Docker) |
|
||||
| 모듈의 `api`·`implementation` 범위, 공개 시그니처, `app.messaging` 설정 타입 | `./gradlew :messaging:messaging-testkit:repositoryContractTest` |
|
||||
| `build.gradle`, `build-logic/`, registry, workflow | `scripts/verify.sh pr`(lane 단계 검사가 workflow를 읽는다) |
|
||||
| 의존성 버전, lockfile | `./gradlew resolveAndLockAll --write-locks` 후 `scripts/verify.sh pr`, 릴리스 전이면 `scripts/verify.sh release` |
|
||||
| 테스트 컨테이너 이미지(`config/testing/container-images.properties`) | `scripts/verify.sh main`. Kafka 이미지가 바뀌면 인증 manifest도 다시 만든다(위 `messaging-kafka` 줄) |
|
||||
|
||||
## 3. 증거로 남길 때
|
||||
|
||||
- 게이트, rc, 실행 직전 부하(`uptime`), 로그 경로, 대상 트리(커밋 또는 `git write-tree`), 캐시를 썼는지를 적는다.
|
||||
- 증거로 쓰는 실행은 `--rerun-tasks`로 캐시 결과를 쓰지 않는다. 테스트 수는 `build/test-results/**.xml`에서 센다.
|
||||
- 인증 증거 줄의 `gitCommit`은 lane이 `GITHUB_SHA`(없으면 `local`)로 적는 출처다. 게이트는 `gitCommit`·`observedAt`을 빼고 시나리오 집합을 비교한다.
|
||||
@@ -0,0 +1,88 @@
|
||||
# 릴리스 — 태그에서 Gitea Packages까지
|
||||
|
||||
이 문서는 messaging-library 버전을 내는 절차다. 버전을 내는 사람(소유자)과 릴리스를 준비하는 에이전트가 읽는다.
|
||||
|
||||
```text
|
||||
main 병합 ──> 소유자가 태그 vX.Y.Z push ──> .gitea/workflows/release.yml (desktop-runner)
|
||||
└─ ./gradlew releaseCheck release
|
||||
1. 태그 형식·버전 확인 (verifyReleaseVersion)
|
||||
2. hermetic lane + integration lane + 브로커 인증 증거 게이트
|
||||
(testLaneCheck, integrationCheck, verifyMessagingCertificationEvidence)
|
||||
3. SBOM 만들기 (releaseSbom, Trivy CycloneDX)
|
||||
4. 의존성 취약점 검사 (HIGH·CRITICAL, KEV) — 여기까지 실패하면 아무것도 안 올라간다
|
||||
5. 모든 모듈 + SBOM 서명해서 올리기 (publish…ToGiteaRepository)
|
||||
6. 익명으로 maven-metadata.xml을 읽어 새 버전 확인
|
||||
```
|
||||
|
||||
## 1. 비밀 값 — 소유자가 둔다
|
||||
|
||||
에이전트는 토큰·키를 만들거나 secret에 넣지 않는다. 소유자가 2026-11-08에 repo secret 셋을 등록했다.
|
||||
|
||||
| secret | 무엇 | 바꿀 때 |
|
||||
| --- | --- | --- |
|
||||
| `PACKAGE_TOKEN` | Gitea 개인 토큰. 권한은 `package` 읽기·쓰기만(repository·user 권한 없음). Gitea job 토큰(`GITEA_TOKEN`)은 패키지를 올릴 수 없어서 사람 토큰이 필요하다 | Gitea 웹 → 설정 → 애플리케이션에서 새로 만들어 secret을 덮어쓰고 옛 토큰을 지운다 |
|
||||
| `SIGNING_KEY` | 서명용 PGP 비밀 키(ASCII armor 전체). 두 라이브러리(grpc, messaging)가 같은 키를 쓴다 | 새 키 쌍을 만들고 README 「서명」의 공개 키와 지문을 같은 PR에서 바꾼다. 만료(2028-11-07) 전에 한다 |
|
||||
| `SIGNING_PASSWORD` | 그 키를 만들 때 정한 암호 한 줄. 키 파일이나 그 base64가 아니다 | 키와 함께 |
|
||||
|
||||
- 이름: 설계(design-docs `repo-structure/05-library-repos.md` 7절)는 `PACKAGES_TOKEN`이라고 적었지만, 등록된 이름 `PACKAGE_TOKEN`에 workflow와 빌드를 맞췄다. 소유자에게 다시 등록을 부탁하지 않는다.
|
||||
- 서명 키: RSA 4096, 지문 `92646CEAFE816CF8B9C249F0A1C936D7F791F8AB`, 2028-11-07 만료. 공개 키는 README 「서명」이다.
|
||||
- 첫 태그는 `v1.0.0`이다(3절).
|
||||
|
||||
**`SIGNING_KEY`에 넣는 것**은 키 지문이나 키 ID(16진수 40·16·8글자)가 아니라 비밀 키 파일 전체다. 파일 그대로(여러 줄)나 그 파일을 base64로 한 줄로 만든 값(`base64 -w0 signing-key.asc`) 둘 다 된다. 빌드가 base64를 풀어 쓴다(`SigningKeys`).
|
||||
|
||||
```bash
|
||||
gpg --armor --export-secret-keys 92646CEAFE816CF8B9C249F0A1C936D7F791F8AB > signing-key.asc
|
||||
```
|
||||
|
||||
1. `signing-key.asc`를 열어 첫 줄 `-----BEGIN PGP PRIVATE KEY BLOCK-----`부터 끝 줄 `-----END PGP PRIVATE KEY BLOCK-----`까지 줄바꿈 그대로 복사한다. RSA 4096 키면 100줄 남짓이다.
|
||||
2. Gitea → 그 repo(grpc-library, messaging-library 둘 다) → 설정 → Actions → Secrets → `SIGNING_KEY`를 고쳐 붙여 넣는다.
|
||||
3. Actions → `signing-check` → Run workflow(main). 로그에 `PROBLEM` 줄이 없고 `gpg import: ok, secret key fingerprint 92646CEA…F791F8AB`, `signing with SIGNING_PASSWORD: ok`가 나오면 된다. 이 workflow는 값을 출력하지 않는다(`scripts/release/check-signing-key.sh`).
|
||||
4. `signing-key.asc`를 지운다(`shred -u signing-key.asc`).
|
||||
|
||||
## 2. 버전 규칙
|
||||
|
||||
- SemVer, repo 하나에 버전 하나. 모든 모듈이 같은 버전으로 나간다. 태그는 `vMAJOR.MINOR.PATCH`이고 접미사(`-rc.1` 등)는 없다. 다른 모양의 태그는 `ca.java-conventions`가 빌드 전에 거부한다.
|
||||
- 공개 타입의 삭제·시그니처 변경, 설정 키(`app.messaging.*`) 바꾸기, 적용된 migration의 위치(`db/migration/messaging`)·내용 바꾸기는 MAJOR다. migration은 원래 고치지 않는다(새 버전 파일을 더한다). 커밋 제목에 `!`, 본문에 `BREAKING CHANGE:`, `CHANGELOG.md` 그 버전 절에 옮기는 법을 쓴다.
|
||||
- 기능 추가는 MINOR, 고치기는 PATCH다.
|
||||
- SNAPSHOT은 내지 않는다. Gitea는 같은 버전을 다시 받지 않는다. 개발 중 연결은 composite build로 한다(`docs/work/README.md` 3절).
|
||||
- **배포한 버전은 지우지 않는다.** 잘못 나갔거나 일부만 올라갔으면 그 버전은 버리고 다음 PATCH를 낸다. Gitea는 owner의 삭제를 막지 않으므로 이것은 규칙으로 지킨다.
|
||||
|
||||
## 3. 버전 내기
|
||||
|
||||
1. main이 초록인지 본다(main.yml 마지막 실행).
|
||||
2. `CHANGELOG.md`에 그 버전 절을 쓰고 PR로 병합한다.
|
||||
3. 올리기 전까지를 desktop에서 미리 돌려 본다(비밀 값 없이, 4절). 비밀 값을 넣거나 바꾼 뒤 첫 태그라면 `signing-check` workflow도 한 번 돌린다(1절).
|
||||
4. 태그를 단다.
|
||||
|
||||
```bash
|
||||
git tag -a v1.0.0 -m "messaging-library 1.0.0"
|
||||
```
|
||||
|
||||
```bash
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
5. release.yml 실행이 초록인지 Gitea Actions 화면에서 본다. 마지막 줄들에 모듈마다 `published: dev.cakit.messaging:<모듈>:<버전>`이 찍힌다.
|
||||
6. 템플릿 PR로 카탈로그 버전(`messagingLibrary`)을 올린다. 절차는 템플릿 `docs/work/reference/related-repos.md`다.
|
||||
|
||||
## 4. 올리기 직전까지 미리 돌리기
|
||||
|
||||
```bash
|
||||
scripts/verify.sh release --on desktop
|
||||
```
|
||||
|
||||
`releaseRehearsal`이 `releaseCheck`를 돌고, 모든 모듈과 SBOM을 `build/staging-repository`에 올린 뒤 파일마다 확인한다(jar·sources·javadoc·POM·module 파일, 체크섬 넷, POM·module의 모든 의존성에 버전이 있는지). `SIGNING_KEY`가 환경에 있으면 `.asc`도 확인한다. 버전은 `RELEASE_VERSION`이 없으면 `0.0.0`이다.
|
||||
|
||||
## 5. 실패했을 때
|
||||
|
||||
| 어디서 | 뜻 | 할 일 |
|
||||
| --- | --- | --- |
|
||||
| 1~4단계, 서명 | 아무것도 올라가지 않았다 | 고쳐서 main에 병합한다. 그 버전의 파일이 Packages에 하나도 없으면(`maven-metadata.xml`에 없음) 태그를 지우고 고친 main 커밋에 같은 태그를 다시 단다. 하나라도 올라갔으면 다음 PATCH를 쓴다 |
|
||||
| 서명 직전 `verifySigningKey`, 또는 `Could not read PGP secret key` | 서명 비밀 값이 키로 읽히지 않는다 | `signing-check` workflow의 `PROBLEM` 줄이 원인이다(지문을 넣음, 줄바꿈 잃음, BEGIN·END 줄 빠짐, base64 손상, 다른 키, 암호 칸에 키를 넣음, 틀린 암호). 1절대로 다시 넣는다 |
|
||||
| 5단계 중간 | 일부 모듈만 올라갔을 수 있다 | 그 버전은 버린다(지우지 않는다). 원인을 고치고 다음 PATCH를 낸다. `CHANGELOG.md`에 버린 버전을 적는다 |
|
||||
| 6단계 | 올라갔지만 익명으로 안 읽힌다 | owner 공개 설정을 확인한다. 템플릿 이미지 빌드가 토큰 없이 읽는다는 전제(설계 8.3절 R1)가 깨진 것이다 |
|
||||
|
||||
## 6. 취약점 정책
|
||||
|
||||
- Trivy(버전·SHA-256은 `scripts/tool.sh`)가 커밋된 lockfile을 본다. HIGH·CRITICAL은 막고, MEDIUM·LOW는 보고만 하고, CISA KEV 목록에 있으면 등급과 상관없이 막는다. KEV 목록을 못 받으면 막는다.
|
||||
- 예외는 `.trivyignore.yaml` 한 곳에만 둔다. 항목마다 이유(`statement`)와 90일 안의 만료(`expired_at`)를 적고 PR로 넣는다.
|
||||
Reference in New Issue
Block a user