docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다 #1

Merged
donghyeon.kang merged 3 commits from docs/library-guides into main 2026-11-08 04:51:01 +00:00
Owner

무엇을, 왜

템플릿에서 옮겨 온 문서가 템플릿 안의 optional build를 전제로 했고(-p platforms/optional-build, 템플릿 registry·workflow 경로), 하네스 뼈대의 루트 지침과 문제 정의는 비어 있었다. 이 repo를 처음 여는 사람과 에이전트가 무엇을 지키고 어떻게 검증·릴리스하는지 이 repo 안에서 알 수 있게 한다.

고른 방법과 버린 대안

  • 루트 AGENTS.md(38줄)·CLAUDE.md, README(받는 법·지원 표·이력), docs/work/README.md·gates.md·release.md, CHANGELOG.md, docs/README.md, scripts/verify.sh 단계(unit·pr·main·release).
  • 살아 있는 문서(family AGENTS.md, 지원 매트릭스, runbook)는 이 repo 기준으로 고쳤다. ADR·설계서 본문은 기록이라 두었다.
  • docs/vision.md는 소유자가 쓰는 문서라 비워 두었다.

위험과 영향

  • 첫 커밋은 문서와 scripts/verify.sh만 바꾼다. verify.sh의 --on desktop 운반부는 하네스 뼈대 그대로이고 이 repo에서 원격으로는 돌려 보지 않았다.

  • 두 번째 커밋은 배포 설정을 바꾼다: 배포 토큰 secret 이름은 설계 05의 PACKAGES_TOKEN이 아니라 소유자가 등록한 PACKAGE_TOKEN이다. 다시 등록을 부탁하지 않고 release.yml·빌드·문서를 그 이름에 맞췄다. 실제 업로드는 태그를 단 release 실행에서야 시험된다.

  • 세 번째 커밋은 build-logic 사본의 ModuleRegistry가 registry 행의 build 칸을 거절하게 한다. 템플릿 구조 리뷰가 찾은 구멍(main이 아닌 값의 모듈이 조용히 빌드에서 빠짐)이 이 사본에도 있었다. 지금 registry에는 그 칸이 없어 동작 변화는 없다.

검증

  • scripts/verify.sh docs rc=0(AGENTS.md 38/40줄, 장부 JSON).
  • 이 PR의 pr.yml(./gradlew ci, verifyStrictLaneStages --dry-run): run 3(첫 커밋)·run 4(두 번째 커밋) 성공, 세 번째 커밋은 다음 실행.
  • desktop: 세 커밋 뒤 트리에서 ci --rerun-tasks, verifyStrictLaneStages --dry-run, releaseRehearsal(RELEASE_VERSION=1.0.0).

리뷰어가 볼 곳

docs/work/release.md 1절(소유자가 둔 비밀 값 셋, 첫 태그), README 「받는 법」·「서명」, .gitea/workflows/release.yml의 env.

관련

design-docs repo-structure/05-library-repos.md 14.2절.

## 무엇을, 왜 템플릿에서 옮겨 온 문서가 템플릿 안의 optional build를 전제로 했고(`-p platforms/optional-build`, 템플릿 registry·workflow 경로), 하네스 뼈대의 루트 지침과 문제 정의는 비어 있었다. 이 repo를 처음 여는 사람과 에이전트가 무엇을 지키고 어떻게 검증·릴리스하는지 이 repo 안에서 알 수 있게 한다. ## 고른 방법과 버린 대안 - 루트 `AGENTS.md`(38줄)·`CLAUDE.md`, README(받는 법·지원 표·이력), `docs/work/README.md`·`gates.md`·`release.md`, `CHANGELOG.md`, `docs/README.md`, `scripts/verify.sh` 단계(unit·pr·main·release). - 살아 있는 문서(family `AGENTS.md`, 지원 매트릭스, runbook)는 이 repo 기준으로 고쳤다. ADR·설계서 본문은 기록이라 두었다. - `docs/vision.md`는 소유자가 쓰는 문서라 비워 두었다. ## 위험과 영향 - 첫 커밋은 문서와 `scripts/verify.sh`만 바꾼다. `verify.sh`의 `--on desktop` 운반부는 하네스 뼈대 그대로이고 이 repo에서 원격으로는 돌려 보지 않았다. - 두 번째 커밋은 배포 설정을 바꾼다: 배포 토큰 secret 이름은 설계 05의 `PACKAGES_TOKEN`이 아니라 소유자가 등록한 `PACKAGE_TOKEN`이다. 다시 등록을 부탁하지 않고 `release.yml`·빌드·문서를 그 이름에 맞췄다. 실제 업로드는 태그를 단 release 실행에서야 시험된다. - 세 번째 커밋은 build-logic 사본의 `ModuleRegistry`가 registry 행의 `build` 칸을 거절하게 한다. 템플릿 구조 리뷰가 찾은 구멍(main이 아닌 값의 모듈이 조용히 빌드에서 빠짐)이 이 사본에도 있었다. 지금 registry에는 그 칸이 없어 동작 변화는 없다. ## 검증 - `scripts/verify.sh docs` rc=0(AGENTS.md 38/40줄, 장부 JSON). - 이 PR의 `pr.yml`(`./gradlew ci`, `verifyStrictLaneStages --dry-run`): run 3(첫 커밋)·run 4(두 번째 커밋) 성공, 세 번째 커밋은 다음 실행. - desktop: 세 커밋 뒤 트리에서 `ci --rerun-tasks`, `verifyStrictLaneStages --dry-run`, `releaseRehearsal`(RELEASE_VERSION=1.0.0). ## 리뷰어가 볼 곳 `docs/work/release.md` 1절(소유자가 둔 비밀 값 셋, 첫 태그), README 「받는 법」·「서명」, `.gitea/workflows/release.yml`의 env. ## 관련 design-docs `repo-structure/05-library-repos.md` 14.2절.
donghyeon.kang added 1 commit 2026-11-08 02:31:49 +00:00
옮겨 온 문서는 템플릿 안의 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).
donghyeon.kang added 1 commit 2026-11-08 04:06:15 +00:00
소유자가 repo secret 셋을 등록했다(2026-11-08): PACKAGE_TOKEN,
SIGNING_KEY, SIGNING_PASSWORD. workflow·빌드·문서는 설계 05 7절의
PACKAGES_TOKEN(S 있음)을 읽고 있어서, 태그를 달면 release가 「token is
not set」으로 멈췄을 것이다. 소유자에게 다시 등록을 부탁하지 않고 등록된
이름에 맞춘다.

- release.yml env와 secret 참조, root build.gradle과
  LibraryPublishingPlugin의 환경 변수 이름을 PACKAGE_TOKEN으로.
- docs/work/release.md 1절을 「소유자가 둔 비밀 값」 표로 바꿨다(무엇,
  바꾸는 법, 설계와 이름이 다른 이유, 서명 키 지문·만료).
- README 「서명」에 공개 키(RSA 4096, 지문 92646CEA…F791F8AB, 2028-11-07
  만료)와 확인 명령을 넣었다.

검증: scripts/verify.sh docs rc=0. 빌드 쪽은 이 PR의 pr.yml 실행.
donghyeon.kang added 1 commit 2026-11-08 04:25:27 +00:00
build-logic 사본의 ModuleRegistry는 행마다 `build` 칸을 읽었다(템플릿의
두 번째 빌드용). 이 repo에는 빌드가 하나라, main이 아닌 값(오타 포함)을
적은 모듈은 settings가 include하지 않고 방향 검사도 보지 않는데 ci는
초록으로 남는다. 템플릿 구조 리뷰가 같은 구멍을 템플릿 쪽에서 찾았다.

칸이 있으면 read에서 실패한다. 시험은 칸이 없으면 main, 칸이 있으면
(빈 값 포함) 그 모듈 id와 'build'를 이름 대고 거절함을 본다.
UPSTREAM.md 「고친 것」에 적었다.

검증: 템플릿에서 같은 시험이 고치기 전 실패(RED), 고친 뒤 통과(GREEN)를
desktop에서 봤다. 이 repo에서는 desktop ci(buildLogicTest 포함).
donghyeon.kang merged commit bbe49accf8 into main 2026-11-08 04:51:01 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/grpc-library#1