Files
grpc-library/docs/work
DongHyeonka 732cb26eb5
pr / ci (pull_request) Successful in 3m42s
fix(release): SIGNING_KEY에 지문이 들어간 경우를 이름 대고 넣는 법을 적는다
signing-check(run 10)로 v1.0.0 서명 실패의 원인을 찾았다. SIGNING_KEY
secret은 40글자 한 줄이었고 BEGIN·END 줄이 없었다. base64로 읽으면 30바이트,
첫 패킷 tag 55(0x37)였다. 16진수 40글자 지문 `92…`를 base64로 읽으면
첫 바이트가 0xF7, 곧 tag 0x37이다. 비밀 키 대신 키 지문이 들어갔다.

- check-signing-key.sh: 값이 16진수 8·16·40글자(키 ID·지문)면 그렇다고
  말한다. 릴리스 키 지문과 같으면 그것도 말한다(공개 정보만 비교한다).
- release.md 1절: SIGNING_KEY에 넣을 것(export 파일 전체, 줄바꿈 그대로),
  넣는 곳, signing-check로 확인하는 법. 3절: 비밀 값을 바꾼 뒤 첫 태그 전에
  signing-check. 5절: 서명 실패 행. 아무것도 게시되지 않았으면 태그를 고친
  커밋으로 옮겨 같은 버전을 쓴다는 규칙(총괄 결정과 같게).

검증: 지문 40글자를 넣은 경우 rc=1과 「key ID or fingerprint (the release
key's fingerprint)」. 앞 커밋의 시험 다섯은 그대로 통과한다.
2026-11-08 15:07:06 +09:00
..

작업 방법 — 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를 끼운다. 파일은 바꾸지 않는다.

    ./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로 넣는다(첫 커밋들만 예외였다).