| work_id | wonffice-release-flow |
|---|---|
| artifact_type | delivery_policy |
| status | qa_ready |
| owner_role | release-manager |
| source_request | 이슈 병렬 개발, 필수 CI, 출시 시점과 버전 관리 정리 |
| last_updated | 2026-09-23 |
이 문서는 개발·출시 정책이다. 출시 준비 완료 기록이 아니다. 클라우드 SaaS와 고객사 내부 설치 제품을 같은 버전으로 동시에 출시한다. 출시 날짜와 통합 후보는 아직 확정하지 않았다. 실제 인수 결과는 #322에서 추적한다.
- 기준점: #248, PR #250. 필수 CI 통과 후 main에 병합했다. 현재 검토 배치는 최신 develop 또는 Planner가 지정한 승인된 로컬 통합 커밋을 기준으로 한다.
- 코어 기반: #249의 transaction 복구는 PR #266으로 병합했다. 이 결과는 서비스 통합 인수를 대체하지 않는다.
- 이 정책: #251. 문서 작업도 지정된 검토 기준의 독립 worktree에서 진행한다.
- 필수 검사 이름은
Lint, type-check, unit test,E2E (editor-react)다. develop 검토 배치와 main 출시 PR에서 필수 검사를 통과하지 않으면 병합하지 않는다. - PR #256에서 실제 ESLint와
pnpm preflight를 연결했다. push 전에 로컬 lint·소스 타입·테스트 타입 검사를 실행한다. 기존 lint·타입 부채는 기준으로 명시하고 증가시키지 않는다. 상세 범위는 로컬 사전 검사를 따른다. - 현재 CI는 서비스 출시 검사 전체를 포함하지 않는다. 네 제품의 전체 사용자 흐름, 서버 격리, 두 배포 환경, 업데이트·복원 검사는 추가 구현 대상이다.
- 기존 Changesets 설정과 npm 버전 이력은 유지한다. 과거 npm release workflow와 Wonffice 서비스 릴리즈는 별개다. PR #250에서 과거 workflow를 제거했으므로 자동 Version Packages PR·npm 게시가 작동한다고 가정하지 않는다. 후속 이슈에서 게시 권한과 검사를 포함해 다시 연결한다.
- Codex 작업을 시작하거나 재개하면 열린 이슈, PR, 최신 댓글을 확인한다. 앱을 열기만 하면 작업이 시작되는 상주 실행기는 만들지 않는다.
- Planner가 승인된 이슈 중 선행 작업이 끝난 단위를 선택한다. 목적, 제외 범위, 완료 기준, 검증 방법, 선행 이슈, 목표 milestone을 기록한다.
- 최신
origin/develop또는 Planner가 지정한 정확한 승인 커밋에서codex/<issue>-<name>브랜치와 별도 worktree를 만든다. 선행 PR의 병합 상태와 로컬 통합 순서를 확인한다. 오래된 기준에서 선행 코드를 다시 만들지 않는다. - 구현 후
.nvmrc의 Node로pnpm preflight를 실행한다. lint와 타입 오류는 push 전에 수정한다. 변경에 맞는 단위·브라우저 검사도 실행한다. 공유 코어 변경은 사용하는 제품의 영향을 확인한다. 모바일 화면 검사는 별도 요청 전까지 제외한다. - 독립 Review가 작업 단위의 정확한 커밋을 승인하면 순서대로 로컬 통합 브랜치에 반영한다. Planner가 검토된 단위를 배치로 고른 뒤 base가 develop인 PR을 만든다. 미검증 작업은 게시하지 않는다. 완료 기준을 충족할 때만
Closes #N을 쓴다. - 병합 직전에 최신 요구와 PR head SHA를 확인한다. develop 변경 후 필요한 재검사와 필수 CI를 통과해야 한다. 실패한 검사를 관리자 우회로 넘기지 않는다.
- 출시 후보는 develop에서 main으로 가는 별도 PR로 검토한다. 두 브랜치의 PR 병합은 고객 배포나 npm 게시를 뜻하지 않는다.
독립된 소유 파일·계약·worktree를 지정한다. 같은 계약을 바꾸는 작업은 순서대로 검토하고 통합한다. Planner가 배치 범위와 PR을 정한다. Agent는 구현과 검증을 수행한다. 최종 출시 결정과 고객 약속은 제품 소유자가 담당한다.
| 변경 경로 | 검증 실행 | 게시 경계 |
|---|---|---|
| 작업 브랜치 → develop PR | 공통 CI와 변경 경로에 맞는 backend·문서 검사 | 검토된 배치만 게시 |
| develop push | 공통 CI와 변경 경로에 맞는 backend·문서 검사 | 문서 빌드는 가능, Pages 배포는 차단 |
| develop → main PR | 공통 CI와 변경 경로에 맞는 backend·문서 검사 | 출시 후보를 별도 검토 |
| main push | 공통 CI와 변경 경로에 맞는 backend·문서 검사 | 문서 Pages 배포 조건 유지 |
| 원인 | 처리 | 병합 |
|---|---|---|
| 코드 또는 테스트의 실제 결함 | 원인 수정 또는 해당 변경 되돌리기, 회귀 검사 추가 | 수정한 head의 검사 통과 후 |
| 운영체제·Node·도구 불일치 | 지원 환경에서 동작하도록 수정, 환경을 명시 | 해당 환경 검사 통과 후 |
| 확인된 일시적 인프라 장애 | 근거를 남기고 같은 head를 한 번 재실행 | 필수 검사 통과 후 |
| 간헐 실패 | 재현 조건·로그·담당 이슈 확보, 경합 또는 검사 설계 수정 | 원인 해결과 검증 후 |
| 기존 기술 부채 | 기준값과 영향 기록, 증가 금지 | 승인된 기존 기준을 충족할 때 |
실패할 때마다 통과할 때까지 재실행하거나 단언을 삭제하지 않는다. 데이터 유실·저장·권한·마이그레이션 검사를 임의로 제외하지 않는다. 검사를 격리해야 한다면 별도 검토에서 사유, 대체 검사, 담당자, 복원 기한을 정한다. 지금 필수 검사 설정은 유지한다.
| 단계 | 검사 범위 | 도입 상태 |
|---|---|---|
| 작업 중 | 변경 모듈과 의존 모듈, 회귀 사례 | 현재 수행 |
| PR | lint, 소스·테스트 타입, 전체 단위 검사, React E2E | 현재 필수; 기존 타입 예외·기준값은 별도 존재 |
| main | 전체 회귀 검사와 통합 제품 smoke 검사 | 기존 CI + 제품 smoke 확대 필요 |
| 출시 후보 | 네 제품 데스크톱 흐름, 두 배포 방식, 격리·저장·업데이트·복원 | 구현 필요 |
검사 비용이 커지면 PR 검사에 의존 관계 기반 영향 분석을 도입할 수 있다. 먼저 전체 검사와 비교하여 누락이 없음을 입증한다. 필수 판정 job은 누락·취소·실패를 성공으로 처리하지 않는다. 이 정책만으로 현재 CI 범위를 줄이지 않는다.
| 단계 | 제품 버전 예시 | 통과 조건 |
|---|---|---|
| 내부 alpha 준비 | 1.0.0-alpha.1 |
기준점 CI 안정화, transaction 복구, 공통 작업 계약, 두 환경 설치·로그인·Note 서버 저장·재열기 검증. 내부 범위 결과를 외부 제공 가능으로 표시하지 않음 |
| 외부 alpha | 확정 전 | Note 다음 Word·Slides·Site까지 실제 로컬 PostgreSQL 메타데이터·Fastify API·제품 UI와 Yorkie 원문 저장·두 계정 실시간 동시편집을 같은 후보에서 검증. SaaS·내부 설치 인수와 사용자 안내도 별도 확인 |
| 제한된 고객 beta | 1.0.0-beta.1 |
Note·Word·Slides·Site 서버 저장·재열기·공유, 회사/사용자/자산 격리, 기본 백업·복구, 지원 범위 명시. 두 배포 방식 제공 |
| 출시 후보 RC | 1.0.0-rc.1 |
기능 범위 동결. 동시 편집 충돌·재접속, 권한 회수, 고객별 기능 차단, 이전 후보에서 업데이트, 실패 복구, 내부 설치 오프라인 기본 작업 검증 |
| 첫 정식 출시 | 1.0.0 |
RC의 두 환경 검증 통과, 출시 차단 결함 없음, 관측·복구 절차·설치 문서 준비, 제품 소유자의 출시 결정 |
내부 alpha 준비는 WP-01·02·05·06의 핵심 경로다. 사용자의 추가 결정에 따라 외부 alpha에는 네 제품의 실제 DB 저장과 실시간 공동 편집 검증도 필요하다. 이전의 beta·RC 단계 표기가 이 조건을 뒤로 미루지 않는다. 일부 선행 기능을 통과했다고 해당 WP 전체를 완료 처리하지 않는다. WP 정의는 전달 계획을 따른다.
독립 상주 Agent 실행기(WP-03·04), 모든 회사 업무 자동화(WP-12 이후), 모바일 편집은 첫 출시의 선행 조건이 아니다. 첫 서비스 범위와 장기 비전을 구분한다. 준비되지 않은 기능은 UI와 API 모두에서 차단한다.
내부 alpha 검증 후 남은 이슈의 규모로 beta 목표 날짜를 정한다. beta 결과로 RC 날짜를 정한다. RC에서는 새 기능을 추가하지 않는다. 데이터 유실·회사 간 자료 노출·설치/저장 불능·복구 실패가 있으면 출시를 보류한다. 일정을 맞추려고 두 배포 방식 중 하나를 제외하지 않는다. 일정 또는 출시 범위를 바꿀 때는 제품 소유자가 결정한다.
Note를 먼저 구현·검증하고 Word, Slides, Site로 확대한다. 네 제품 모두 통과하기 전에는 외부 alpha를 완료로 표시하지 않는다. 각 제품에서 실제 로컬 PostgreSQL, 인증한 서로 다른 계정 두 개, Fastify API, 제품 UI, 실제 Yorkie 연결을 사용한다. 외부 alpha의 협업 서비스는 Yorkie Cloud다. 내부 통합 검증에는 외부 Yorkie 연결을 허용하며 로컬 자체 설치는 필수가 아니다. 최종 테스트 배치는 미정이다. Cloud 연결을 완전 오프라인 검사라고 부르지 않는다.
Yorkie는 동시편집 상태와 협업 원문을 소유한다. Wonffice API·PostgreSQL은 계정·회사·권한·문서 메타데이터를 소유한다. 이미지와 첨부는 별도 파일 저장소에 둔다. Wonffice가 인증과 접근 제어를 책임진다. 기존 Yjs·Automerge 코드는 이번 결정만으로 삭제하거나 병행 구현 대상으로 정하지 않는다.
| 검사 | 실제 확인할 결과 |
|---|---|
| 저장·재열기 | UI 입력 후 Yorkie 협업 원문과 화면의 내용·구조·서식, API·PostgreSQL의 문서 메타데이터·권한 관계가 일치. 브라우저와 서버 재시작 후 재열기 |
| 두 사용자 동시편집 | 독립 브라우저 세션에서 같은 문서 수정. 양쪽 변경 수렴과 새로고침·재접속 후 영속 결과 일치 |
| 실패·복구 | 연결 단절, 서버 재시작, 저장 실패와 재시도. 저장 확인된 변경과 미확정 입력 구분, 유실·중복 검사 |
| 구조·이력 | 지원 구조 변경과 사용자별 undo/redo. 다른 사용자의 확정 변경 보존 |
| 권한·저장 소유권 | 권한 없는 접근과 권한 회수 후 읽기·쓰기 거부. 오래된 snapshot이 공동 편집의 새 변경을 덮어쓰지 않음 |
같은 후보 commit, 포함 PR head, 앱 산출물 digest, PostgreSQL·인증·Yorkie 버전, 합성 자료, 실제 실행한 명령·로그, 제품별 QA 판정을 연결한다. 상세 시나리오는 #322를 사용한다. DB CRUD, 브라우저 로컬 저장, snapshot revision 충돌, 협업 adapter 또는 단위 검사만으로 통합 인수를 통과 처리하지 않는다. 서로 다른 후보의 통과 결과를 합산하지 않는다.
Backend·제품 담당은 구현과 실제 API/DB 확인 경로를 제공한다. Operator는 재현 가능한 로컬 기동·재시작·복원 절차와 후보 산출물을 제공한다. QA는 독립 실행 결과를 기록한다. Writer는 검증된 동작으로 시작 안내·사용 방법·지원 범위·알려진 제한·문제 해결·업데이트 및 사용자 조치를 작성한다. 실행하지 않은 명령과 확인하지 않은 동작은 미확인으로 표시한다. 로컬 통과는 SaaS·내부 설치 환경의 설치·권한·저장·백업·복원 인수를 대체하지 않는다. 최종 범위와 출시 판단은 Product Master PM이 관리한다.
제품 버전은 Wonffice 서비스 전체의 배포 조합이다. Git tag는 wonffice-v1.0.0-alpha.1처럼 제품 이름을 포함한다. 루트 package.json의 기존 1.0.0은 첫 서비스가 출시되었다는 증거가 아니다. 제품 전체를 대표하는 비공개 workspace 패키지의 package.json을 제품 버전의 단일 기준으로 둔다. 이 패키지도 Changesets로 버전과 변경 내역을 관리하지만 npm에는 게시하지 않는다. 프런트엔드 office-app 하나의 버전을 전체 제품 버전으로 사용하지 않는다. 릴리즈 manifest는 이 제품 버전을 읽고 코드·이미지·DB 조합을 기록한다. 제품 버전과 manifest 검증 기반은 #252 / PR #254에서 main에 병합됐다. 게시된 태그의 불변성 검증과 실제 배포는 후속 구현 대상이다.
| 변화 | 제품 버전 규칙 |
|---|---|
| 기존 공개 API·고객 확장 계약과 호환되지 않음 | major |
| 기존 계약을 유지하는 기능 추가 | minor |
| 기존 계약을 유지하는 결함 수정 | patch |
| 정식 출시 전 검증 후보 | alpha, beta, rc와 순번 |
문서 형식·DB migration은 별도 식별자와 호환 범위를 manifest에 기록한다. 내부 스키마 변경만으로 major를 올리지는 않는다. 기존 문서나 지원 고객 확장 계약을 깨면 호환성 변경으로 취급한다. 패치라도 DB 변경이 있으면 복구 검사가 필요하다. 버전 번호만으로 마이그레이션 순서를 추정하지 않는다.
npm 패키지는 Changesets의 독립 버전을 유지한다. 변경한 공개 패키지와 필요한 내부 의존 패키지의 버전을 조정한다. 이미 배포한 @barocss/* 버전을 제품 버전에 맞춰 초기화하지 않는다. 고객사별 기능은 같은 제품 버전에 설치 목록과 설정으로 관리한다. 고객사별 브랜치·별도 제품 버전을 만들지 않는다.
제품 동작을 바꾸는 PR에는 제품 패키지 changeset을 기록한다. 라이브러리도 바뀌면 해당 공개 패키지를 같은 changeset 또는 별도 changeset에 추가한다. 개발 도구·문서만 바꾸면 제품 버전을 올리지 않는다. 비공개 패키지의 버전 관리 설정을 명시하고, 제품 버전과 manifest 버전이 다르면 검증에 실패하도록 한다. npm 게시와 SaaS·내부 설치 배포는 각각의 검사와 실행 단계로 유지한다.
공개 라이브러리 변경 PR에는 pnpm changeset으로 patch/minor/major와 설명을 기록한다. 문서·테스트만 바뀌면 changeset을 요구하지 않는다. 서비스 UI 변경만으로 관련 없는 모든 라이브러리를 올리지 않는다. 다만 배포 라이브러리의 동작이 바뀌면 해당 패키지 changeset이 필요하다. Version Packages PR에서 실제 버전과 내부 의존성 변경을 검토한다. npm 게시 workflow는 별도 검증을 마친 후 활성화한다.
출시 manifest에는 제품 버전, Git commit SHA, 이미지 digest, 사용 패키지 버전, 문서 schema, DB migration 집합, 지원하는 업그레이드 출발 버전, 검증 결과 링크를 기록한다. 같은 버전·태그·산출물을 덮어쓰지 않는다. 패키지 npm tag와 제품 tag를 구분한다.
한 번 빌드한 이미지를 검증 환경에서 통과시킨 뒤 SaaS와 내부 설치 묶음에 같은 digest로 사용한다. RC와 정식 출시가 같은 이미지를 쓰면 정식 manifest에서 검증된 후보 digest를 참조한다. 앱 표시용 배포 버전은 manifest에서 읽고 빌드 SHA는 별도로 노출하는 방식으로 구현한다. 코드·내장 버전·설정 변경으로 이미지를 다시 빌드했다면 새 후보로 다시 검사한다.
main 병합은 배포 버튼이 아니다. 릴리즈 PR에 manifest, 변경 내역, 업그레이드 경로, 알려진 제한, 검사 결과를 모은다. 소유자가 이를 확인한 후 같은 버전의 SaaS 전환과 내부 설치 묶음을 공개한다. 부분 실패는 두 형태 동시 출시 완료로 기록하지 않는다.
- 출시 전 백업을 생성하고 복원 시간을 실제로 측정한다. 허용 중단 시간과 데이터 손실 범위는 고객 약속 전에 확정한다.
- DB와 이전 앱이 호환되면 이전 이미지로 복구할 수 있다. 호환되지 않으면 무조건 downgrade하지 않는다. 검증된 백업 복원 또는 전진 수정을 선택한다.
- 파괴적 migration은 별도 변경으로 처리한다. 가능한 경우 추가→전환→제거 순서를 사용한다.
- 로그인 실패, 저장 실패, revision 충돌, 공유 권한 오류, 작업 큐 지연, migration 실패를 관측한다. 정상 기준과 중단 기준은 후보 검증 결과에서 수치로 정한다.
- 출시 담당은 제품 소유자다. Agent는 검사·배포 준비·복구 절차를 실행 가능한 형태로 만든다. 운영 데이터 손실이나 확정하지 않은 고객 약속을 Agent가 임의로 승인하지 않는다.
- #322에서 공식 통합 후보와 남은 WP-02·05·06 및 실시간 협업 구현의 상태를 추적한다.
- Backend·제품 담당이 Note의 DB·API·UI·협업 경로를 연결한 뒤 Word·Slides·Site로 확대한다. Operator가 실제 실행 환경과 명령을 기록한다.
- QA가 네 제품의 로컬 통합 인수를 같은 후보에서 수행한다. SaaS와 내부 설치의 환경별 결과도 별도로 기록한다.
- Writer가 실제 동작에 맞춘 사용자 안내와 제한·복구·업데이트 문서를 준비한다. PM이 증거와 위험을 검토한 뒤 출시 시점과 외부 범위를 결정한다.
- Semantic Versioning 2.0.0: 호환성 기준의 버전 증가, 사전 출시 식별자, 출시 후 불변성.
- Changesets 사용 안내: 변경 기록, 버전 적용, 패키지 게시의 분리.
- GitHub 보호 브랜치: 필수 상태 검사와 최신 기준 브랜치 검증.
라이브러리 게시 절차는 npm 패키지 출시 문서에 둔다. main에는 수동 게시용 .github/workflows/npm-release.yml과 버전 PR용 .github/workflows/npm-version.yml이 있다. 실제 게시 대상·권한·npm 결과는 제품 배포와 별도로 확인한다. 제품 배포가 라이브러리를 자동 게시하지 않는다.