버전 관리 · 릴리즈¶

코드가 브랜치에서 시작해 배포되어 사용자에게 닿기까지 한 흐름을 담는다 — 브랜치·PR·리뷰(버전 관리)부터 테스트·배포·릴리즈노트·롤백(릴리즈)까지. 전략은 GitHub Flow다(소규모 팀에서 빠르게 배포하고 리뷰 중심으로 협업하기에 맞다). 모노레포 구조는 ADR-0003, 배포 파이프라인 자체(워크플로·트리거)는 infra §2-3.

1. 브랜치 전략 — GitHub Flow¶

main(또는 develop)에서 갈라 → PR → 리뷰 → merge로 이어지는 단순한 흐름. 복잡한 버전·릴리즈 관리 없이 단일 메인 브랜치를 늘 최신으로 유지한다. Git Flow를 안 쓴 이유는 분명하다 — 브랜치 관리 비용이 높고 PR 중심 리뷰 구조를 만들기 어려워 소규모 팀에 안 맞는다. GitHub Flow는 단순해 학습·관리 비용이 낮고, 메인 머지만으로 즉시 배포되며, 그 와중에도 PR 리뷰 문화를 유지한다.

표준 6단계 흐름: 1. 브랜치 생성 — 메인을 부모로, 기능/버그 작업 브랜치를 그때그때 분기. 2. 개발·수정 — 기능 단위 커밋, 메시지는 정확·간결하게(§2). 서버의 동일 브랜치에 push. 3. PR 생성 — 기능/수정 완료 시 PR. 4. 리뷰·논의 — PR로 팀원 리뷰·토론(§3). 5. 공개·테스트 — 머지 전 브랜치 상태에서 CI(GitHub Actions)로 테스트 자동화. 오류 시 이전 메인을 재배포해 rollback. 6. Merge — 검증 완료 시 메인에 머지 → 곧 배포 트리거.

배포 트리거 연동: develop 머지 → Dev 배포(온프레/Vercel), main 머지 → Prod(AWS). infra §2-3.

브랜치 네이밍 (`<prefix>/<작업 내용>`)¶

prefix	용도	예시
`feat/`	새 기능	`feat/user-login`
`fix/`	버그 수정	`fix/login-error`
`refactor/`	구조 개선(기능 변경 X)	`refactor/service-cleanup`
`setting/`	빌드/배포/인프라/설정	`setting/github-actions`
`hotfix`	운영 긴급

실제 운영에선 Vercel 프리뷰 alias용 DEDU-/FE-/QA- prefix 브랜치도 쓴다(infra §2-4 프리뷰 CORS).

2. 커밋 메시지¶

<type>: <subject>
<BLANK LINE>
<body>   (선택, 설명 필요 시)

type	when	type	when
feat	기능 추가	docs	문서
update	기능 수정	style	오타·공백·스타일(기능 무관)
fix	버그 수정	test	테스트 코드
refactor	리팩토링	setting	개발 환경 세팅
		chore	유지보수

3. Pull Request · 코드 리뷰¶

Pn 룰 — P1(Request changes): 적극 고려, 수용 또는 합당한 의견으로 토론. P2(Comment): 웬만하면 반영, 못 하면 사유/후속 티켓. P3(Approve): 반영해도/넘어가도 OK.

머지 룰 — 지정 리뷰어 1명 리뷰하면 머지 가능, 머지 버튼은 리뷰이(작성자) 가 누름. PR에 연관 이슈 번호 입력 → GitHub 자동 감지·mention.

4. 이슈 운영¶

GitHub Issues → New Issue → 템플릿 선택. 메타: Assignees·Labels·Project(자동 포함). Milestone 미사용. PR에서 이슈 번호 연동하면 close 시 Project가 자동 Done. 주석은 직관적 네이밍 + 적극 주석으로 문서화, 예정 작업은 TODO.

5. 테스트 전략¶

"개발 30%, 테스트 70%"라는 감각으로 본다. 테스트 코드는 비공식 문서 역할을 하며 배포·리팩토링의 안정성을 받쳐 준다. 커버리지 100%를 좇기보다 핵심 로직(주요 비즈니스 로직, 자주 바뀌는 코드, 외부 시스템 통합의 실패·예외 경로)에 집중한다. 방법론은 TDD(Red-Green-Refactor, 유닛) / BDD(Given-When-Then, 통합·E2E).

유형	대상	툴
유닛	단위 로직	JUnit, Mockito
통합	내부 기능	`@SpringBootTest`/`@MockBean`, TestContainers
계약	API 일관성	Spring Cloud Contract, Pact
E2E	시나리오 전체	Playwright(프론트), Cypress/Selenium
성능	부하·응답시간	JMeter, Gatling, nGrinder

CI에서 ./gradlew build -x test — 빌드/테스트 단계 분리(infra §2-3).

6. 배포 (트리거별)¶

대상	트리거	결과
Dev 백엔드	`develop` 머지 + `mvp-back/**`	self-hosted runner → GHCR → 온프레 `docker run` + 헬스 게이트(응답 확인, 실패 시 중단)
Dev 프론트	`develop` 머지 + `mvp-front/**`	`git subtree split` → the-edu-project push → Vercel 자동 빌드
Prod 백엔드	`main` 머지	AWS Lightsail (Flyway `flywayValidate` 통과 필수, 실패 시 배포 중단)

위험 단계는 한 번에 몰아치지 말고 헬스 게이트 출력(200/RestartCount)을 확인한 뒤 다음으로. 파이프라인 상세는 infra §2-3.

7. 릴리즈 — 무엇을 신경쓰나 (릴리즈노트 · 체크리스트)¶

배포가 곧 릴리즈다. 릴리즈 때마다 "무엇이 바뀌었고 무엇을 봐야 하는지"를 남긴다 — 그래야 다음 릴리즈가 같은 함정을 피한다.

릴리즈노트는 기능별로 쌓인다. 각 기능의 2-product/build/lines/<라인>/<기능>/release-notes(append-only)에 릴리즈마다 한 블록씩 — 무엇을 바꿨나 · 깨질 위험(breaking) · 마이그레이션 필요 여부 · 롤백 계획. 완료 여부는 본문에 단정하지 말고 GitHub Issue 링크로(이슈 닫히면 완료).

릴리즈 전 체크리스트(게이트) — 머지·배포 직전 한 번 훑는다: - 배포 URL이 맞는지(인터랙션 URL과 배포 URL 혼동 주의), 권한별 화면이 구현됐는지. - 도메인별 미해결(로그인·스터디룸·수업노트·학생 리스트·질문)을 체크박스로 추적. - 검색·복제·삭제·편집 이벤트의 API 연동 누락을 게이트로 막는다. - DB 변경이 있으면 Flyway 마이그레이션이 들어갔는지(Prod는 flywayValidate 통과 필수).

배포 직후 스모크 테스트(핵심 동선 최소 검증): 1. 인증 — 로그인/로그아웃 · 회원가입 · 401 시 /login 리다이렉트 2. 스터디룸 — 선생님: 생성→수업노트 작성 / 학생: 입장→조회→질문 등록 3. 과제 — 선생님: 생성→마감일 / 학생: 제출 4. 온보딩 — 회원가입→역할 선택→프로필 5. 초대 플로우

8. 롤백¶

Dev 백엔드: 헬스 실패 시 알림 + 중단(이전 이미지 롤백보다 우선 — 잘못된 이미지가 떠 있는 상태를 막는 게 먼저).
일반 운영 롤백: 이전 메인 브랜치 상태 재배포(§1 6단계).
인프라 레이어 장애(컨테이너 통신 단절 등)는 incidents 런북의 진단/복구 스크립트를 따른다.

복구 검증: 백엔드 헬스 200 · RestartCount=0 · docker inspect|grep VAR로 env 확인(infra §2-5). 스모크 5개 통과. Prod는 Flyway flywayValidate 통과. Vercel 빌드 성공 + dev.d-edu.site 로딩 + 쿠키 도메인(.d-edu.site) 정상.

9. 에스컬레이션¶

배포·CI 실패: 담당 BE/FE → @eng-lead. 인프라 레이어(네트워크·호스트) 의심 시 인시던트로 승격해 incidents에 4블록(발생→원인→복구→재발방지) append. ("코드 안 바꿨는데 깨짐"이면 러너 이미지·Docker 버전 등 외부 드리프트를 먼저 의심.)
알파/UX 검증 이슈: Jira 코멘트 타임로그 + UX 피드백 + 이슈 티켓.

부록. 알파테스트 (MS2 — UX 검증)¶

기능이 도는지보다 사용자의 UX 흐름과 정보구조가 자연스러운지를 본다. 강사·학생·학부모 역할별 E2E를 더미 계정으로 직접 체험한다. 범위는 역할별 E2E(회원가입 생략, 더미 계정), 기간은 테스트 2일+정리 1일, GA 구축 전후로 두 번. 기록은 Jira 코멘트 타임로그 + UX 피드백 + 이슈 티켓, 산출물은 역할별 체험 보고서·UX 개선안·Top 이슈 리포트. 관찰의 핵심은 "처음 써 보는 사람이라면?" — 기대한 흐름이 없어 멈추는 지점(비밀번호 찾기·문의·로그아웃·홈 이동 누락 등)을 가장 큰 리스크로 본다. 프리티어 성능 저하는 "느려도 괜찮은가"가 아니라 "느릴 때도 UX가 자연스러운가"로 평가한다. 더미 계정 비밀번호는 raw에만.