Release and PyPI lifecycle

버전은 다섯 곳에서 동시에 움직입니다

버전 문자열은 다섯 곳에 살고, 같은 커밋에서 함께 갱신해야 합니다. CHANGELOG.md, pyproject.toml, CLAUDE.md, README.md, README.ko.md. 사이트 쪽은 npm run sync-stats(site/scripts/sync-stats.mjs)가 SoT와 changelog 데이터를 재생성합니다. 한 곳이라도 어긋나면 geode version 출력과 패키지 메타데이터가 불일치합니다.

SemVer 기준

MAJOR. 호환성 파괴. CLI 플래그 제거, 공개 API 리네임.
MINOR. 운영자가 선언한 마일스톤 전용. deprecation 문자열에 예약된 번호(removed in v…)를 먼저 확인.
PATCH. 기본값 — 새 기능·버그 수정·리팩토링 등 일상 릴리스 전부(0.99.x patch-train의 연속).
문서만 바뀌면 버전을 올리지 않습니다.

wheel이 소유하는 설치 경계

geode-agent wheel은 Python 생태계의 불변 제품 설치물입니다. 네 개 CLI와 core, evals, evolve 코드, 승인된 builtin skill, 정적 reference input을 함께 버전 관리합니다. 실행 중 생성되거나 계속 바뀌는 데이터는 wheel에 쓰지 않습니다.

wheel 안	wheel 밖
런타임·평가·evolve 코드와 console entry point	`GEODE_HOME`의 상태·로그·생성 helper
정확히 열거된 builtin skill과 immutable reference input	rolling ledger, 결과 파일, 사용자·프로젝트 skill
읽기 전용 helper source	`GEODE_EVOLVE_WORKSPACE`가 가리키는 실제 Git checkout

따라서 설치된 geode-evolve는 reference input을 읽을 수 있지만 mutation과 promotion에는 writable GEODE checkout이 필요합니다. computer-use helper의 생성물은 GEODE_HOME/helpers/computer-use에 놓입니다. 별도 core, eval, evolve wheel은 독립 설치 계약이나 릴리스 주기가 실제로 생기기 전까지 만들지 않습니다.

릴리스 흐름

평소에는 feature가 develop으로 머지됩니다. 릴리스는 릴리스 준비용 topic 브랜치가 버전 스탬프와 CHANGELOG 정리를 싣고 develop에 먼저 머지된 뒤, develop이 main으로 그대로 통과합니다. 승격 직전에는 두 원격 브랜치를 fetch하고 내용을 비교합니다. main에 고유 커밋이 있고 strict 최신 상태 조건을 충족해 머지할 수 있으면 현재 main head에서 develop로 직접 CI-gated PR을 엽니다. 충돌이나 strict ancestry 조건이 이를 막으면 현재 develop에서 sync/main-into-develop-* 브랜치를 만들고 현재 main을 명시적 merge commit으로 병합합니다. 복사나 fast-forward로 만든 sync head는 허용하지 않습니다. 부모는 현재 develop, 현재 main 순서로 정확히 두 개여야 합니다. merge 직전에 trust resolver를 다시 실행하고, merge guard가 같은 부모 검증을 실제 원격 tip에 적용합니다. strict 보호, 관리자 적용, 현재 PR에 연결된 필수 Actions 검사 성공은 유지합니다. 자동 backmerge workflow는 없습니다.

# 1. CHANGELOG [Unreleased] → [X.Y.Z] - YYYY-MM-DD; 빈 [Unreleased] 유지
# 2. 다섯 위치 동시 bump (CHANGELOG / pyproject / CLAUDE.md / README.md / README.ko.md)
# 3. main drift: strict 조건 충족 시 main → develop, 충돌·ancestry 차단 시 trusted sync
# 4. topic → develop → main: 각 PR의 실제 head에서 필수 CI green 확인
#    PR 본문은 Summary / Why / Changes / Verification 유지
# 5. 패키지 배포는 main 머지로 자동 발화하지 않음. 아래 워크플로우를 수동 dispatch

release.yml은 수동 전용입니다

main 푸시는 CI와 Pages만 돌립니다. 패키지 배포는 .github/workflows/release.yml을 workflow_dispatch로 직접 실행해야 하고, 배포 잡들은 보호된 release 환경을 지납니다.

입력	의미
`ref` / `version`	릴리스할 ref와 기대 버전. 메타데이터 불일치는 validate 단계에서 실패
`publish_stable`	GitHub Release와 PyPI를 한 승격으로 출하 (기본 false)
`publish_huggingface_artifacts`	버전드 릴리스 번들을 HF dataset repo로 업로드 (기본 false)

validate-build 잡이 lint와 hygiene, 타입 체크, 프롬프트 무결성, 공식 문서 생성 게이트, 테스트, 런타임 E2E 스모크, twine check를 모두 통과해야 배포 잡이 시작됩니다. stable promotion은 현재 origin/main SHA를 사용하고, 복구 실행에서는 변경되지 않은 기존 annotated tag target만 허용합니다. 그 뒤 annotated tag와 GitHub Release, Trusted Publishing, 공개 PyPI exact-version 설치 검증을 거칩니다. 마지막 읽기 전용 검증기는 tag target, GitHub asset, PyPI 파일, SHA-256이 모두 같은 릴리스인지 확인합니다. clean-wheel gate는 설치된 distribution 파일 전체의 digest가 거부된 evolution mutation 뒤에도 같은지, mutable experiment state가 빠졌는지, 정확한 builtin-skill allowlist와 설치된 daemon IPC 버전이 맞는지도 함께 검증합니다.

릴리스 후 설치 갱신

PyPI/uv stable 설치는 geode update로 갱신합니다. 기본 명령은 현재 major/minor의 최신 patch만 허용하고, minor/major는 --latest를 명시해야 합니다. updater는 설치 metadata와 prospective version을 먼저 검증하고, 실행 중 daemon을 package 교체 전에 중지합니다. stop 실패면 설치를 건드리지 않고, install 실패면 중지 상태를 유지하며, 성공한 재시작은 CLI와 IPC가 같은 버전일 때만 완료됩니다.

geode update                  # 최신 호환 patch
geode update --latest         # minor/major를 명시적으로 허용
geode version                 # 공개 버전 확인

저장소에서 작업하는 editable [audit] 개발 설치는 stable wheel과 별개입니다. 이 경우에만 daemon을 직접 중지하고 checkout을 재설치합니다. [audit] extra가 빠지면 inspect_ai 기반 평가를 실행할 수 없습니다.

pkill -f "geode serve" || true
uv tool install -e ".[audit]" --force --python 3.12
uv sync --extra audit
geode version
geode serve &

릴리스와 PyPI 라이프사이클