옮겨 온 문서는 템플릿 안의 optional build를 전제로 했다(`-p platforms/optional-build`, 템플릿 registry·workflow 경로, "벤더드 플랫폼"). 하네스 뼈대의 루트 지침과 문제 정의는 비어 있었다. - 루트 AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것(core-api 순수성, Stable이 advanced를 안 씀, 템플릿에 기대지 않음, 배포한 버전 불변, 버전 규칙), 지도, 맡은 일, 검증 진입점. 비대화형 세션의 플러그인 설치 두 줄. - README: 무엇인가, 받는 법(exclusiveContent), 지원 표, 구조, 문서 지도, 서명, 이력(filter-repo, 커밋 SHA·리뷰 ID는 템플릿 기준). - docs/work/README.md·gates.md·release.md: 고치는 법, 단계와 바꾼 것별 게이트, 템플릿과 같이 고치기(composite), 릴리스와 소유자가 할 일 (PACKAGES_TOKEN, SIGNING_KEY·SIGNING_PASSWORD, 첫 태그 v1.0.0). - CHANGELOG.md(1.0.0 미발행, 옮기는 법), docs/README.md(지도, 머리 블록). - scripts/verify.sh: unit·pr·main·release 단계. 라이브러리라 app은 없다. - 살아 있는 문서(grpc·grpc-advanced AGENTS.md, 지원 매트릭스, runbook): 경로·패키지·optional build 문장을 이 repo 기준으로. ADR·설계서 본문은 기록이라 고치지 않았다. - docs/vision.md는 소유자가 쓰는 문서라 비워 두었다. 검증: scripts/verify.sh docs rc=0(AGENTS.md 38줄, 장부 JSON).
This commit is contained in:
@@ -0,0 +1,30 @@
|
||||
# 문서 지도
|
||||
|
||||
## 1. 어디에 무엇이 있나
|
||||
|
||||
| 폴더 | 종류 | 고치는 법 |
|
||||
| --- | --- | --- |
|
||||
| `work/` | 작업 방법(고치기, 게이트, 릴리스) | 살아 있는 문서. 동작이 바뀌면 같은 변경에서 고친다 |
|
||||
| `compatibility/` | 지원 매트릭스(무엇을 인증했나) | 살아 있는 문서 |
|
||||
| `runbooks/` | 운영 대응 | 살아 있는 문서 |
|
||||
| `adr/` | 결정 기록(ADR-GRPC-*) | 기록. 본문은 고치지 않는다 |
|
||||
| `design/` | 설계서 | 기록. 본문은 고치지 않는다 |
|
||||
| `ledger/` | 예측·실측 장부 | 줄을 더하기만 한다 |
|
||||
| `vision.md`, `problem-statement.md` | 방향, 풀 문제 | `vision.md`는 소유자만 쓴다 |
|
||||
|
||||
## 2. 기록 문서의 머리 블록
|
||||
|
||||
`adr/`와 `design/`의 문서는 맨 위에 머리 블록을 둔다. 본문은 쓴 때의 원문이고, 지금도 맞는지는 머리 블록이 말한다.
|
||||
|
||||
```markdown
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택 | 대체됨(무엇으로) | 폐기
|
||||
- 작성일: YYYY-MM-DD
|
||||
- 요약: 한 문장
|
||||
- 현재 정본: 지금 동작을 설명하는 살아 있는 문서 경로
|
||||
<!-- 머리 블록 끝 -->
|
||||
```
|
||||
|
||||
지난 결정이 바뀌면 본문은 두고 「상태」와 「현재 정본」만 고친다. 템플릿에서 옮겨 온 기록의 본문 경로(`src/platforms/…`, `.github/workflows/…`)는 그 결정 때의 템플릿 경로다.
|
||||
@@ -3,8 +3,8 @@
|
||||
Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이
|
||||
요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.
|
||||
|
||||
릴리스 gate는 `.github/workflows/release.yml`의 `grpc-stable-release-gate` job이다. 인증된 lane마다 아무것도 돌리지 않으면
|
||||
실패하는 strict test lane이다.
|
||||
릴리스 gate는 `.gitea/workflows/release.yml`이 돌리는 Gradle 단계 `releaseCheck`다(`docs/work/release.md`). 인증된 lane마다
|
||||
아무것도 돌리지 않으면 실패하는 strict test lane이다.
|
||||
|
||||
> 이력: 코드 안의 `GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` 짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드
|
||||
> 코드도 그것을 부르지 않아서 아무것도 막지 않았다.
|
||||
@@ -26,9 +26,9 @@ Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Java | 21 |
|
||||
| Spring Boot | 저장소 기준선, `src/gradle/libs.versions.toml`(계획은 4.1을 가정한다) |
|
||||
| io.grpc | `src/gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
|
||||
| Protobuf | `src/gradle/libs.versions.toml`의 protobuf 항목(어느 leaf가 어느 것을 쓰는지는 그 파일의 주석이 적는다) |
|
||||
| Spring Boot | `gradle/libs.versions.toml`의 `springBoot`(이 줄로 컴파일하고 시험한다. 버전별 표는 README 「지원 표」) |
|
||||
| io.grpc | `gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
|
||||
| Protobuf | `gradle/libs.versions.toml`의 `protobufGrpc`(생성 코드 runtime과 protoc가 같은 줄) |
|
||||
| Stable 전송 | Netty(shaded) |
|
||||
| Stable RPC 모양 | Unary, Server Streaming |
|
||||
| Stable resolver | Static, DNS, Unix domain socket |
|
||||
@@ -63,8 +63,8 @@ in-process 결과는 절대 전송 증거가 아니다. in-process 전송은 TLS
|
||||
|
||||
## 지금 릴리스 상태
|
||||
|
||||
릴리스하지 않았다. registry에서 모든 `:grpc:*` leaf는 `"build": "optional-grpc"`라 주 빌드 밖에 있고 어느 조립에도 들어가지
|
||||
않는다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 산출물 어디에도 실리지 않는다.
|
||||
Gitea Packages에 아직 버전을 내지 않았다(첫 버전은 `v1.0.0`, `docs/work/release.md`). 이 라이브러리를 조립하는 앱도
|
||||
아직 없다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 앱 어디에도 실리지 않는다.
|
||||
|
||||
릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.
|
||||
|
||||
|
||||
@@ -5,30 +5,38 @@
|
||||
|
||||
## 고객의 말 그대로
|
||||
|
||||
- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다)
|
||||
- 소유자(2026-11-07): 「템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리 폴더가 있으면 안 된다. 커스텀 라이브러리는 별도 repo로 관리하고, 매뉴얼에 관리 대상으로 둔다.」
|
||||
- 고객은 이 라이브러리를 받아 쓰는 백엔드 서비스(백엔드 템플릿과 그 파생 서비스)와 그 서비스를 만드는 사람·에이전트다.
|
||||
|
||||
## 지금은 어떻게 버티나
|
||||
|
||||
- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용)
|
||||
- 2026-11-08까지 이 코드는 템플릿 안의 두 번째 Gradle 빌드(`src/platforms/optional-build`)였다. 템플릿 빌드 규칙·카탈로그·testFixtures를 경로로 읽었고, 템플릿 CI가 job 넷과 단계 하나로 따로 돌렸다.
|
||||
- 템플릿을 받은 파생 서비스는 쓰지도 않는 플랫폼 코드 수백 파일을 함께 받았다. 템플릿 재사용 체크리스트(「`dev.caskeleton`을 새 패키지로 바꾼다」)가 플랫폼 패키지까지 바꾸게 만들었다.
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능)
|
||||
- 템플릿 `adapter:inbound:grpc`를 이 라이브러리에 배선하는 일. 별도 결정이다(`grpc/AGENTS.md` 「application이 이 family에 도달하는 경로」).
|
||||
- Maven Central 배포. 템플릿 밖 공개 소비자가 생기면 본다.
|
||||
- BOM. 소비자가 템플릿 하나라 카탈로그 버전 한 칸으로 충분하다. 템플릿 밖 소비자가 한 라이브러리에서 모듈 3개 이상을 쓰면 다시 본다.
|
||||
- SNAPSHOT 배포. 같이 고칠 때는 composite build를 쓴다.
|
||||
|
||||
## 성공 기준
|
||||
|
||||
| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 |
|
||||
|---|---|---|---|---|
|
||||
| (채울 것) | | | | |
|
||||
| 혼자 빌드된다 | 템플릿 없이 PR·main 단계가 초록 | Gitea Actions `pr`·`main` 실행 결과 | 초록 | 2026-11-08 |
|
||||
| 배포된다 | 태그 하나로 서명된 모든 모듈이 Gitea Packages에 올라가고 익명으로 읽힌다 | release.yml, `maven-metadata.xml` | `v1.0.0` 게시 | 소유자가 비밀 값을 넣은 뒤 |
|
||||
| 템플릿이 가벼워진다 | 템플릿에 gRPC 플랫폼 폴더·optional build·그 CI job이 없다 | `git ls-files src/platforms/grpc*` | 0 | 2026-11-08 PR |
|
||||
|
||||
## 세 관점 점검
|
||||
|
||||
| 관점 | 묻는 것 | 답 |
|
||||
|---|---|---|
|
||||
| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) |
|
||||
| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) |
|
||||
| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) |
|
||||
| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | 템플릿 유지비를 줄인다. 대가는 CI·build-logic 사본·release secret이 한 벌 더 생기는 것 |
|
||||
| 기술 | 만들 수 있나, 가장 위험한 가정은 | Gitea Packages가 Gradle이 올리는 체크섬 넷과 `.asc`·`.module`을 모두 받는다는 가정(설계 16절 H8). 첫 태그에서 드러난다 |
|
||||
| 고객 | 쓸모 있나, 지금 방법보다 나은가 | 쓰는 서비스는 버전으로 받고, 쓰지 않는 서비스는 아무것도 받지 않는다 |
|
||||
|
||||
## 되돌릴 수 없는 결정
|
||||
|
||||
- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다)
|
||||
- 배포한 버전은 지우지 않는다(`docs/work/release.md` 2절). 같은 버전은 다시 올릴 수 없다.
|
||||
- Maven group `com.hyeonworks.grpc`와 proto 패키지 `hyeonworks.grpc.*`. 바꾸면 모든 소비자의 MAJOR다. 근거는 design-docs `repo-structure/05-library-repos.md` 6.3절.
|
||||
|
||||
@@ -47,7 +47,7 @@ xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 **더하
|
||||
**거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다.
|
||||
proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다.
|
||||
`GrpcWebProxyContract.violations`가 정확히 이것을 보고하고, 참조 설정
|
||||
`src/platforms/grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다.
|
||||
`grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다.
|
||||
|
||||
**메서드가 client streaming이나 bidirectional streaming이면** gRPC-Web으로는 아예 되지 않는다. 브라우저는
|
||||
메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Runbook: gRPC platform operations
|
||||
|
||||
범위: `:grpc:*` family. 지금은 모두 빌드만 된다. registry에서 이 family의 leaf는 모두 `"build": "optional-grpc"`
|
||||
(주 빌드 밖, `-p platforms/optional-build`로 돈다)이고 어느 조립에도 들어가지 않으므로, 여기 있는 것은 아직 운영에서
|
||||
범위: `:grpc:*` family. 지금은 모두 빌드만 된다. 이 라이브러리를 실제로 쓰는 앱은 아직 없다(백엔드 템플릿의
|
||||
`adapter:inbound:grpc`도 이 라이브러리가 아니라 `io.grpc`를 직접 쓴다). 그래서 여기 있는 것은 아직 운영에서
|
||||
일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼
|
||||
수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다.
|
||||
|
||||
@@ -156,5 +156,5 @@ snapshot에는 해시와 이름만 실린다. 자격 증명처럼 보이는 이
|
||||
- **운영의 reflection.** `GrpcReflectionMode.defaultFor`는 `STAGE`와 `PROD`에 `DISABLED`를 돌려준다. reflection은
|
||||
연결을 열 수 있는 누구에게나 스키마 전체를 공개한다.
|
||||
- **모든 advanced capability.** `docs/runbooks/grpc-advanced-capabilities.md`를 본다.
|
||||
- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, registry에서 모든 `:grpc:*` leaf는
|
||||
`"build": "optional-grpc"`라 기본 조립에 들어가지 않는다.
|
||||
- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, 앱이 이 라이브러리를 의존성으로 받지 않으면
|
||||
아무것도 조립되지 않는다.
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
# 작업 방법 — grpc-library를 고칠 때
|
||||
|
||||
이 repo에서 일을 맡은 사람과 에이전트가 먼저 읽는다. 루트 `AGENTS.md`의 「꼭 지킬 것」이 이 문서보다 먼저다.
|
||||
|
||||
## 1. 일의 종류와 읽을 곳
|
||||
|
||||
| 일 | 먼저 읽을 곳 | 끝났다는 증거 |
|
||||
| --- | --- | --- |
|
||||
| 모듈 코드 고치기·기능 더하기 | 그 family의 `AGENTS.md`(`grpc/`, `grpc-advanced/`), 관련 ADR(`docs/adr/`) | 바꾼 모듈 `check` + `ci`(2절) |
|
||||
| proto 바꾸기 | `grpc/grpc-contract/buf.yaml`, ADR-GRPC-002 | `ci`의 `bufLint`·`bufBreaking`. 깨지는 변경이면 MAJOR(`release.md` 2절) |
|
||||
| 공개 타입·설정 키 바꾸기 | `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. 백엔드 템플릿과 같이 고치기
|
||||
|
||||
템플릿이 이 라이브러리를 버전으로 받게 되면(지금은 받지 않는다) 두 repo를 같이 바꾸는 일이 생긴다.
|
||||
|
||||
1. 이 repo와 템플릿에 브랜치를 하나씩 만든다. 두 repo를 같은 부모 폴더에 둔다.
|
||||
2. 템플릿에서 명령 줄로만 이 repo를 끼운다. 파일은 바꾸지 않는다.
|
||||
|
||||
```bash
|
||||
./gradlew --include-build ../grpc-library <태스크>
|
||||
```
|
||||
|
||||
3. 그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다.
|
||||
4. 병합 순서는 하나다: 이 repo PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. 끼운 상태로만 통과하는 템플릿 PR은 병합하지 않는다.
|
||||
5. 공개 API를 바꾸는 PR은 본문에 템플릿 쪽 영향(끼운 상태로 돌린 태스크와 결과)을 적는다.
|
||||
|
||||
## 4. 이 repo에서 정한 것
|
||||
|
||||
- 결정 기록은 `docs/adr/`에 쌓는다. 템플릿에서 옮겨 온 ADR-GRPC-001~006·ADV-001은 번호를 그대로 둔다. 새 결정은 `docs/adr/0000-template.md` 양식으로 `ADR-GRPC-007`부터 쓴다.
|
||||
- 문서는 한국어로 쓴다. 지난 결정을 고칠 때는 본문이 아니라 머리 블록의 「상태」·「현재 정본」만 고친다(`docs/README.md` 2절).
|
||||
- 커밋·PR 규칙은 design-docs `conventions/commit-and-pr.md`다. `main`에는 PR로 넣는다(첫 커밋들만 예외였다).
|
||||
@@ -0,0 +1,30 @@
|
||||
# 게이트 — 무엇을 언제 돌리나
|
||||
|
||||
단계 태스크는 루트 `build.gradle`이 정한다. workflow는 단계마다 Gradle 한 줄이고, 어떤 모듈·lane·검사가 들어가는지는 workflow가 아니라 Gradle이 정한다.
|
||||
|
||||
## 1. 단계
|
||||
|
||||
| 단계 | 언제 | 명령(`scripts/verify.sh`) | 들어 있는 것 |
|
||||
| --- | --- | --- | --- |
|
||||
| `ci` | PR(`pr.yml`) | `pr` | 모듈 `check` 전부(단위 시험, Spotless, Checkstyle, Error Prone, strict lane), SpotBugs(main·test), lockfile, `architectureCheck`, `bufLint`·`bufBreaking`, build-logic 시험. 그리고 `verifyStrictLaneStages --dry-run` |
|
||||
| `mainCheck` | main push·매일 03:00 KST(`main.yml`) | `main` | `ci` + `integrationCheck`(Testcontainers PostgreSQL) + `performanceCheck` |
|
||||
| `releaseCheck` | `vX.Y.Z` 태그(`release.yml`) | `release` | 버전 확인, 인증 lane(`testLaneCheck`), `integrationCheck`, SBOM, 의존성 취약점 검사 |
|
||||
| `release` | `vX.Y.Z` 태그 | — | `releaseCheck` 뒤 Gitea Packages에 서명해 올리고 익명으로 다시 읽는다 |
|
||||
| `releaseRehearsal` | 손으로 | `release` | `releaseCheck` 뒤 `build/staging-repository`에 올리고 파일마다 확인. 비밀 값 없이 돈다 |
|
||||
|
||||
## 2. 바꾼 것에 맞는 게이트
|
||||
|
||||
| 바꾼 것 | 최소로 돌릴 것 |
|
||||
| --- | --- |
|
||||
| 모듈 하나의 코드 | `./gradlew <gradle path>:check`(path는 registry), 끝나기 전에 `scripts/verify.sh pr` |
|
||||
| `grpc-operation-ledger-jpa`, migration | 위 + `./gradlew integrationCheck`(Docker) |
|
||||
| 성능에 닿는 코드(`grpc-testkit` 성능 lane이 보는 곳) | 위 + `./gradlew performanceCheck` |
|
||||
| `.proto`, `buf.yaml` | `./gradlew :grpc:grpc-contract:check :grpc:grpc-contract:bufLint :grpc:grpc-contract:bufBreaking` |
|
||||
| `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` |
|
||||
|
||||
## 3. 증거로 남길 때
|
||||
|
||||
- 게이트, rc, 실행 직전 부하(`uptime`), 로그 경로, 대상 트리(커밋 또는 `git write-tree`), 캐시를 썼는지를 적는다.
|
||||
- 증거로 쓰는 실행은 `--rerun-tasks`로 캐시 결과를 쓰지 않는다. 테스트 수는 `build/test-results/**.xml`에서 센다.
|
||||
- `bufBreaking`의 기준은 PR이면 대상 브랜치와의 merge base, main이면 직전 커밋이다. 로컬에서 다른 기준을 쓰려면 `BUF_AGAINST=<ref>`.
|
||||
@@ -0,0 +1,80 @@
|
||||
# 릴리스 — 태그에서 Gitea Packages까지
|
||||
|
||||
이 문서는 grpc-library 버전을 내는 절차다. 버전을 내는 사람(소유자)과 릴리스를 준비하는 에이전트가 읽는다.
|
||||
|
||||
```text
|
||||
main 병합 ──> 소유자가 태그 vX.Y.Z push ──> .gitea/workflows/release.yml (desktop-runner)
|
||||
└─ ./gradlew releaseCheck release
|
||||
1. 태그 형식·버전 확인 (verifyReleaseVersion)
|
||||
2. 인증 lane + integration lane (testLaneCheck, integrationCheck)
|
||||
3. SBOM 만들기 (releaseSbom, Trivy CycloneDX)
|
||||
4. 의존성 취약점 검사 (HIGH·CRITICAL, KEV) — 여기까지 실패하면 아무것도 안 올라간다
|
||||
5. 모든 모듈 + SBOM 서명해서 올리기 (publish…ToGiteaRepository)
|
||||
6. 익명으로 maven-metadata.xml을 읽어 새 버전 확인
|
||||
```
|
||||
|
||||
## 1. 처음 한 번 — 소유자가 할 일
|
||||
|
||||
에이전트는 토큰·키를 만들거나 secret에 넣지 않는다. 아래는 소유자가 한다.
|
||||
|
||||
1. **배포 토큰 `PACKAGES_TOKEN`**: Gitea 웹 → 설정 → 애플리케이션 → 새 토큰. 권한은 `package` 읽기·쓰기만 준다(repository·user 권한은 주지 않는다). Gitea job 토큰(`GITEA_TOKEN`)은 패키지를 올릴 수 없어서 사람 토큰이 필요하다.
|
||||
2. **서명 키 `SIGNING_KEY`·`SIGNING_PASSWORD`**: PGP 키 쌍 하나를 두 라이브러리(grpc, messaging)가 함께 쓴다.
|
||||
|
||||
```bash
|
||||
gpg --quick-generate-key "hyeonworks release <admin@hyeonworks.com>" ed25519 sign 2y
|
||||
```
|
||||
|
||||
```bash
|
||||
gpg --armor --export-secret-keys <키 ID> > signing-key.asc
|
||||
```
|
||||
|
||||
`signing-key.asc` 내용 전체가 `SIGNING_KEY`, 키를 만들 때 넣은 암호가 `SIGNING_PASSWORD`다. 넣은 뒤 `signing-key.asc`는 지운다. 공개 키(`gpg --armor --export <키 ID>`)는 README 「서명」 절에 붙인다.
|
||||
3. **repo secret 셋**: grpc-library → 설정 → Actions → Secrets에 `PACKAGES_TOKEN`, `SIGNING_KEY`, `SIGNING_PASSWORD`.
|
||||
4. **첫 태그 `v1.0.0`**: 아래 3절을 따른다.
|
||||
|
||||
## 2. 버전 규칙
|
||||
|
||||
- SemVer, repo 하나에 버전 하나. 모든 모듈이 같은 버전으로 나간다. 태그는 `vMAJOR.MINOR.PATCH`이고 접미사(`-rc.1` 등)는 없다. 다른 모양의 태그는 `ca.java-conventions`가 빌드 전에 거부한다.
|
||||
- 공개 타입·proto의 삭제·시그니처 변경, 설정 키(`app.grpc.platform.*`) 바꾸기는 MAJOR다. 커밋 제목에 `!`, 본문에 `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절).
|
||||
4. 태그를 단다.
|
||||
|
||||
```bash
|
||||
git tag -a v1.0.0 -m "grpc-library 1.0.0"
|
||||
```
|
||||
|
||||
```bash
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
5. release.yml 실행이 초록인지 Gitea Actions 화면에서 본다. 마지막 줄들에 모듈마다 `published: com.hyeonworks.grpc:<모듈>:<버전>`이 찍힌다.
|
||||
6. 템플릿이 이 라이브러리를 쓰게 되면(지금은 쓰지 않는다) 템플릿 PR로 카탈로그 버전을 올린다. 절차는 템플릿 `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에 병합하고 같은 태그 이름을 새 커밋에 다시 달지 않는다. 다음 PATCH 태그를 쓴다 |
|
||||
| 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