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의 연속).
문서만 바뀌면 버전을 올리지 않습니다.

릴리스 흐름

평소에는 feature가 develop으로 머지됩니다. 릴리스는 release/* 브랜치가 버전 스탬프와 CHANGELOG 정리를 싣고 develop에 먼저 머지된 뒤, develop이 main으로 그대로 통과합니다. 승격 직전에는 두 원격 브랜치를 fetch하고 내용을 비교합니다. main에 추적 전용 변경이 있고 충돌이 없으면 현재 main head에서 develop로 직접 CI-gated PR을 엽니다. 충돌 해결이 필요할 때만 현재 develop에서 sync/main-into-develop-* 브랜치를 만들고 현재 main을 명시적 merge commit으로 병합합니다. 이 sync head는 두 원격 tip을 정확한 부모로 가져야 하며 merge 직전에 trust resolver를 다시 통과해야 합니다. 자동 backmerge workflow는 없습니다.

# 1. CHANGELOG [Unreleased] → [vX.Y.Z] - YYYY-MM-DD
# 2. 다섯 위치 동시 bump (CHANGELOG / pyproject / CLAUDE.md / README.md / README.ko.md)
# 3. main drift: clean이면 main → develop PR, 충돌 시에만 sync/main-into-develop-*
# 4. release PR: release/* → develop → main (develop→main PR은 Summary + 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이 모두 같은 릴리스인지 확인합니다.

Homebrew는 core 입성 절차가 따로 있습니다

Homebrew는 stable promotion의 일부가 아닙니다. 기존 custom 배포 저장소는 삭제됐고, namespace가 붙는 설치 명령도 다시 만들지 않습니다. packaging/homebrew의 formula template과 renderer는 immutable GitHub Release sdist를 쓰는 geode-agent Homebrew/core 후보만 만듭니다.

첫 upstream PR은 Homebrew의 최신 acceptable-formula 정책을 따릅니다. GEODE가 beta 표기를 벗어나고 외부 사용 및 notability 조건을 충족하기 전에는 검증된 후보를 fork에만 보관합니다. Homebrew/core가 수락한 뒤 공식 formula API와 깨끗한 macOS·Linux 환경에서 unqualified install, version, formula test, uninstall 게이트가 모두 통과해야 공개 설치 화면에 Homebrew를 다시 추가할 수 있습니다. 실제 후보 갱신과 검증 명령은 저장소의 packaging/homebrew/README.md에만 둡니다.

릴리스 후 rebuild

main 머지 후 로컬 런타임을 새 코드로 올립니다. 두 함정이 있습니다. 데몬 정지는 pkill -f를 써야 합니다. ps aux | grep은 긴 파이썬 경로가 잘려 데몬을 못 잡고, 살아남은 옛 데몬이 소켓을 두고 새 데몬과 경합합니다. 그리고 [audit] extra가 필수입니다. 빠지면 inspect_ai가 없어 자기개선 루프의 감사가 측정 대신 실패합니다.

pkill -f "geode serve" || true          # 확인: pgrep -f "geode serve"
uv tool install -e ".[audit]" --force   # [audit] extra 필수 (inspect_ai)
uv sync --extra audit
geode version                            # 버전 일치 확인
geode serve &                            # 데몬 재기동