제품 릴리즈 버전의 기준은 Git tag, CHANGELOG.md, GitHub Release입니다. 서버 Gradle의 version = "0.0.1-SNAPSHOT"은 빌드 도구 metadata일 뿐 제품 버전이 아니고, front/package.json에는 version 필드가 없습니다. 별도 VERSION 파일도 만들지 않습니다.
| 항목 | 역할 |
|---|---|
Git tag vMAJOR.MINOR.PATCH |
배포 가능한 제품 버전, GHCR server image trigger, 수동 frontend 배포의 immutable 입력 |
CHANGELOG.md |
저장소에 남는 버전별 릴리즈 노트 |
| GitHub Release | 공개 사용자와 운영자가 보는 tag별 릴리즈 노트 |
| OCI compose image tag | 서버 배포 시 운영 VM에서 pull하는 container image 식별자. 제품 tag와 맞춰 ghcr.io/<owner>/<repo>/readmates-server:vMAJOR.MINOR.PATCH를 사용 |
제품 버전은 하나입니다. server와 frontend를 따로 버전 관리하지 않고, 같은 Git tag가 backend, frontend, Pages Functions, 배포 script, 문서를 함께 가리킵니다.
ReadMates는 vMAJOR.MINOR.PATCH 형식을 사용합니다.
| 변경 | 예시 | Bump |
|---|---|---|
| 호환성 깨짐 | URL/API/auth/session model을 운영자가 다시 맞춰야 하는 변경 | Major |
| 사용자 기능 또는 운영 기능 추가 | 새 알림 템플릿, 새 호스트 운영 흐름, 새 배포 runtime | Minor |
| 버그 수정, 문서 보강, 작은 UX 수정 | 배포 runbook 보강, regression fix, copy fix | Patch |
minor와 patch 성격이 섞이면 큰 쪽을 고릅니다. DB migration이나 서버 API 변경이 있으면 CHANGELOG.md의 Deployment Notes에 서버 배포 순서와 Flyway 기대 상태를 적습니다.
CHANGELOG.md의Unreleased내용을 새## vX.Y.Z - YYYY-MM-DD섹션으로 옮깁니다.docs/development/release-management.md와 이 문서가 현재 절차와 맞는지 확인합니다.- 변경 범위에 맞는 검증을 실행합니다.
- 릴리즈 문서 변경을
main에 커밋하고 push합니다. - 서버 변경이 있으면 같은 release tag로 GHCR image와 OCI compose 배포를 진행할 계획을 deployment notes에 확정합니다.
git tag -a vX.Y.Z -m "ReadMates vX.Y.Z"를 만들고 push합니다.- Tag push가
.github/workflows/deploy-server.yml을 통해 GHCR scan-candidate image를 만들고, Trivy가 통과한 같은 digest를 release tag로 promote합니다. - 서버 runtime rendering이 바뀌면
sync-config(restart_api=false, dry_run=false)를 성공시킨 뒤 OCI backend를 promote된 GHCR release image tag로 배포하고 Flyway/health/BFF smoke를 확인합니다. - Backend가 새 API contract를 제공하는 것을 확인한 뒤
Deploy Frontworkflow를release_tag=vX.Y.Z로 수동 dispatch해 같은 tag의 Cloudflare Pages frontend와 Pages Functions를 배포합니다. - GitHub Release를 생성하거나 갱신하고, body는
CHANGELOG.md의 해당 버전 섹션과 맞춥니다. gh release view vX.Y.Z --json tagName,name,url,publishedAt로 GitHub Release 객체가 실제로 존재하는지 확인합니다. tag만 있고 release가 없으면 GitHub의 릴리즈 노트 화면에는 아무것도 보이지 않습니다.
main이나 tag push만으로는 frontend 운영 배포가 시작되지 않습니다. backend promotion 뒤에 Deploy Front workflow를 release tag와 함께 수동 dispatch합니다. 그래야 새 frontend가 구 backend에 없는 API를 먼저 부르는 틈이 생기지 않습니다.
Major host-write contract release는 READMATES_HOST_WRITE_CLIENT_CONTRACT_REQUIRED=true를 backend promotion 전에 동기화합니다. 새 backend는 구 browser/BFF의 mutating /api/host/**를 409로 잠시 동결하고, 같은 tag의 새 browser bundle과 Pages BFF가 함께 배포된 뒤에만 write를 재개합니다. Frontend-only rollback은 host write 동결을 유지하므로 호환 frontend 재배포 또는 backend rollback/forward-fix까지 운영 계획에 포함합니다.
OCI compose 배포 script는 READMATES_SERVER_IMAGE가 없으면 readmates-server:local을 사용해 로컬 빌드 이미지를 VM으로 전송합니다. 릴리즈 배포에서는 먼저 Deploy Server Image workflow가 scan-candidate digest를 Trivy로 검사한 뒤 같은 digest를 release tag로 promote했는지 확인하고, 아래처럼 제품 tag와 같은 image tag를 명시합니다.
READMATES_SERVER_IMAGE='ghcr.io/<owner>/<repo>/readmates-server:vX.Y.Z' \
VM_PUBLIC_IP='<vm-public-ip>' \
CADDY_SITE=api.example.com \
./deploy/oci/05-deploy-compose-stack.shRollback은 /opt/readmates/.env의 READMATES_SERVER_IMAGE를 이전 검증 tag로 되돌린 뒤 readmates-api를 다시 올리는 방식입니다. 실제 VM IP, private host, secret, smoke 결과 전문은 Git에 남기지 않습니다.
릴리즈 버전 작업은 아래가 맞을 때 완료입니다.
CHANGELOG.md에 새 버전 섹션, deployment notes, verification 결과가 있습니다.- Git tag, GitHub Release title, 서버 image tag가 같은
vX.Y.Z를 사용하고gh release view vX.Y.Z가 성공합니다. - 서버 변경이 있으면 backend 배포와
/internal/healthsmoke가 통과했거나, 배포 blocker가 명확히 기록되어 있습니다. - 같은 release tag를 입력한 frontend deployment workflow가 backend promotion 뒤 성공했거나, GitHub Actions blocker가 명확히 기록되어 있습니다.
- 공개 릴리즈 후보 scan이 통과했거나, 실행하지 못한 사유가 남아 있습니다.