Contribution Flow

이 문서는 source-repo에서 작업을 시작하고 main에 반영하는 방법을 설명합니다. 목표는 복잡한 규칙을 늘리는 것이 아니라, 작은 팀이 변경 맥락을 잃지 않고 빠르게 통합하는 것입니다.

기본 흐름은 아래 하나입니다.

issue
  -> short-lived branch
  -> pull request
  -> CI + self-review
  -> impact-based human review when needed
  -> squash merge to main

1. 핵심 기준

1-1. `main`은 protected trunk다

main은 release-ready 상태를 유지하는 기준 branch입니다. 직접 commit하지 않고, 모든 변경은 PR로 들어옵니다.

main에 merge되었다는 말은 "모든 변경이 깊게 human-reviewed 되었다"는 뜻이 아닙니다. 이 repo에서는 required CI와 작성자 self-review를 기본 gate로 두고, 위험도가 있는 변경만 별도 human review를 요구합니다.

main에 반영한다는 말은 direct push가 아니라 PR을 merge한다는 뜻입니다. 자동화 도구나 agent도 같은 기준을 따릅니다. 정책 예외로 direct push가 필요하면 요청자가 직접 push를 명시하고, 실행 전에 예외임을 확인해야 합니다.

1-2. PR은 change set 단위다

PR은 사람이 완벽하게 검토한 문서가 아니라, 하나의 목적을 가진 변경 묶음입니다. PR 하나는 가능한 한 하나의 issue를 해결합니다.

좋은 PR은 아래 질문에 답할 수 있어야 합니다.

왜 바꾸는가
무엇을 바꾸는가
어떻게 검증했는가
clinical, contract, data, release/security에 영향이 있는가

1-3. 규칙은 최소로 둔다

GitHub Flow는 branch prefix를 강제하지 않습니다. Conventional Commits도 모든 type을 필수 표준으로 강제하지 않습니다.

그래서 이 repo는 널리 쓰이는 흐름을 따르되, branch prefix와 commit type은 읽기 쉬운 팀 convention으로만 사용합니다.

2. 작업 시작

2-1. Issue를 먼저 만든다

원칙적으로 작업은 issue에서 시작합니다. Issue는 기획서가 아니라 작업 anchor입니다. 나중에 PR, squash commit, release review에서 변경 이유를 찾기 위한 최소 기록입니다.

Issue에는 아래 정도만 있으면 됩니다.

항목	내용
목적	무엇을 바꾸는가
배경	왜 지금 필요한가
범위	이번 PR에 포함할 것과 제외할 것
검증	어떤 command나 CI로 확인할 것인가
Impact	clinical, contract, migration, release, security 영향이 있는가

2-2. Issue type은 크게만 나눈다

Issue type은 GitHub 기본값에 맞춰 크게만 나눕니다.

Type	의미
`feature`	새 기능, 새 API, 새 UI state, 새 package capability
`bug`	기대와 다르게 동작하는 문제나 regression
`task`	문서, test, CI, dependency, 정리 작업

docs, test, ci, build, security, clinical 같은 세부 분류는 issue type으로 늘리지 않습니다. 필요하면 label, PR description, commit scope에 적습니다.

2-3. Issue 없이 시작해도 되는 경우

아주 작은 typo, broken link, 명백한 문구 오류는 issue 없이 PR로 처리할 수 있습니다.

다만 PR description에는 왜 issue 없이 처리했는지, 변경 범위가 작은지, 어떤 검증을 했는지 남깁니다. Clinical, contract, release, security 영향이 있는 변경은 issue 없이 시작하지 않습니다.

3. Branch

3-1. Branch는 짧게 유지한다

Branch는 오래 유지할수록 merge context와 CI 결과가 낡습니다. 며칠 안에 PR로 올릴 수 있을 만큼 작게 유지합니다.

상시 dev 또는 develop branch는 기본 정책에 포함하지 않습니다. 이 repo는 main을 protected trunk로 두고, 짧은 작업 branch를 PR로 자주 합치는 방식을 기본으로 합니다.

3-2. Branch 이름은 읽히면 충분하다

Branch 이름은 issue 번호와 짧은 설명을 포함합니다.

상황	예시
기능	`feature/42-risk-policy`
버그 수정	`fix/57-compose-port`
문서	`docs/63-contribution-flow`
그 외 작업	`task/71-storage-smoke`

Release 안정화가 며칠 이상 필요할 때만 release/x.y branch를 사용합니다. 긴급 수정은 hotfix/<issue>-<short-title>을 사용할 수 있지만, 이 경우에도 PR과 CI를 거칩니다.

4. Commit과 PR Title

4-1. `main`에는 squash commit 하나가 남는다

작업 중 commit은 자유롭게 나눠도 됩니다. 하지만 main에는 PR 단위의 squash commit 하나만 남깁니다.

따라서 최종 history에서 가장 중요한 것은 PR 안의 WIP commit message가 아니라 PR title입니다. PR title은 squash commit으로 남아도 맥락이 이해되어야 합니다.

4-2. PR title은 Conventional Commits 계열을 쓴다

PR title과 squash commit title은 아래 형식을 사용합니다.

<type>(<scope>): <summary>

예시는 아래와 같습니다.

docs(workflow): simplify contribution flow
fix(demo): avoid compose port conflict
feat(api): add alarm audit endpoint

scope는 선택입니다. Conventional Commits는 scope 문법만 제공하고, 표준 scope 목록을 정하지 않습니다. Scope는 codebase의 어느 영역을 바꿨는지 알려주는 짧은 힌트입니다.

Scope가 바로 떠오르지 않으면 생략합니다. 억지로 고르면 history가 오히려 읽기 어려워집니다.

docs: update local development guide
docs(workflow): simplify contribution flow
fix(api): preserve alarm audit events
feat(contracts): add monitoring snapshot schema

4-3. Commit type은 작게 유지한다

매일 쓰는 기본 type은 아래로 충분합니다.

Type	사용할 때
`feat`	사용자나 package consumer가 볼 수 있는 기능을 추가할 때
`fix`	bug나 regression을 고칠 때
`docs`	문서만 바꿀 때
`test`	test, fixture, smoke를 추가하거나 고칠 때
`refactor`	behavior를 바꾸지 않고 구조를 정리할 때
`chore`	코드 behavior와 직접 관련 없는 운영성 작업

필요할 때만 아래 type을 추가로 씁니다.

Type	사용할 때
`ci`	GitHub Actions, CI gate, release automation 변경
`build`	build system, package manager, dependency resolution 변경
`perf`	behavior를 유지하면서 성능만 개선
`revert`	이전 commit 되돌림

style은 기본 type으로 쓰지 않습니다. Formatting-only 변경은 chore(format): ...로 적습니다.

5. Pull Request

5-1. PR description은 짧아도 된다

PR description은 길 필요가 없습니다. 대신 reviewer가 변경의 목적, 범위, 검증 상태를 빠르게 이해할 수 있어야 합니다.

GitHub와 GitLab의 PR/MR template도 관련 issue, 변경 설명, reviewer에게 필요한 맥락을 남기는 용도로 사용됩니다. 이 repo는 SaMD 예제이므로 여기에 짧은 impact check만 추가합니다.

여기서 impact는 정식 risk analysis가 아닙니다. PR 작성자는 "이 변경이 임상 동작, public contract, data migration, release/security 경계에 영향을 주는가"를 표시합니다. 실제 SaMD risk analysis와 safety review는 release, design, clinical review 같은 별도 gate에서 다룹니다.

기본 형식은 아래 정도면 충분합니다.

Issue:
- Closes #

Summary:
- 

Verification:
- 

Impact check:
- clinical: none
- contract/api: none
- migration/data: none
- release/security: none

Reviewer note:
- optional

Impact check는 영향 범위를 빠르게 드러내는 표시입니다. 영향이 없으면 none 또는 N/A라고 적고, 영향이 있으면 어떤 영역인지 한 줄로 남깁니다. 복잡한 PR에서만 Reviewer note에 먼저 볼 파일, review focus, rollout/rollback 주의점을 적습니다.

5-2. 작성자가 먼저 self-review한다

PR을 merge하기 전에 작성자가 먼저 diff를 봅니다.

확인할 것은 아래입니다.

의도하지 않은 파일이 들어가지 않았는가
debug log, generated output, local file이 섞이지 않았는가
secret, token, .env, private key가 들어가지 않았는가
변경 범위에 맞는 command나 CI가 통과했는가
behavior, command, boundary가 바뀌었다면 문서도 바뀌었는가
human review가 필요한 변경인가

6. Review

6-1. Review 강도는 영향 범위에 맞춘다

Review의 목적은 모든 PR을 같은 깊이로 붙잡아 두는 것이 아니라, 변경이 repo의 code health와 SaMD safety boundary를 해치지 않는지 확인하는 것입니다.

기본 gate는 아래입니다.

required CI가 통과해야 합니다.
작성자가 self-review를 해야 합니다.
PR description에 최소한의 verification과 impact check가 남아야 합니다.

여기서 impact check는 긴 문서가 아닙니다. none이라고 판단했다면 그렇게 적고, clinical, contract/api, migration/data, release/security 중 영향이 있으면 reviewer가 바로 알 수 있게 표시합니다.

Human review는 변경 위험도에 따라 요구합니다. 작은 문서 typo나 명백한 cleanup은 CI와 self-review만으로 merge할 수 있습니다. 반대로 clinical behavior, public contract, release path처럼 잘못되면 영향이 큰 변경은 반드시 사람이 한 번 더 봅니다.

6-2. Reviewer가 보는 것

Reviewer는 모든 줄을 취향대로 고치는 사람이 아닙니다. 변경이 의도한 문제를 풀고, 기존 경계를 망가뜨리지 않으며, 필요한 검증이 남아 있는지 확인합니다.

Reviewer는 아래를 우선 봅니다.

확인할 것	질문
목적	PR이 해결하려는 issue나 문제와 diff가 맞는가
영향 범위	public API, contract, storage, release, security, clinical behavior가 바뀌는가
검증	변경 위험도에 맞는 test, smoke, manual check가 남아 있는가
경계	app/package, domain/adapter, source repo/CD repo 책임이 섞이지 않았는가
운영성	rollback, migration, artifact handoff, secret 노출 위험이 있는가

중요하지 않은 문구나 취향 문제는 merge를 막는 blocker로 만들지 않습니다. 꼭 남기고 싶다면 optional comment로 남깁니다.

6-3. Human review가 필요한 변경

아래 변경은 사람이 별도로 확인해야 합니다.

변경	이유
clinical 또는 risk logic	SaMD behavior와 patient safety에 직접 영향을 줄 수 있습니다.
public API, contract, fixture	다른 package, app, 문서 예제가 함께 깨질 수 있습니다.
database migration, storage schema	rollback과 data compatibility 영향이 있습니다.
CI/CD, release, versioning, Nexus, security	artifact publish와 supply-chain trust boundary에 영향을 줍니다.
container publish policy, runtime base image	배포 artifact와 runtime security에 영향을 줍니다.
large refactor, boundary 변경	작성자 혼자 전체 영향 범위를 보기 어렵습니다.

6-4. AI review는 보조 신호다

AI review는 붙일 수 있으면 feedback path에 추가합니다. Typo, missed edge case, test gap, suspicious diff를 빠르게 찾는 데 유용할 수 있습니다.

다만 AI review는 human review가 필요한 변경을 대체하지 않습니다. Clinical, contract, migration, release, security 변경은 책임 있는 사람이 impact와 verification evidence를 확인해야 합니다.

7. Merge

7-1. Merge 조건

PR은 아래 조건을 만족해야 합니다.

조건	설명
Required CI 통과	PR required gate가 통과해야 합니다.
Self-review 완료	작성자가 diff, secret, test, impact check를 확인해야 합니다.
Squash-ready title	PR title이 squash commit으로 남아도 이해 가능해야 합니다.
Publish 없음	PR에서는 package, release image, firmware artifact를 publish하지 않습니다.

7-2. Squash merge 기준

main에는 PR 단위의 squash commit만 남깁니다.

Merge commit을 기본으로 사용하지 않습니다.
WIP commit message는 main history에 남기지 않습니다.
Squash commit title은 PR title을 기준으로 정리합니다.
PR description은 release review에서 change set 맥락을 찾을 수 있게 유지합니다.

8. 참고 기준

8-1. De facto 참고 문서

아래 문서는 이 flow의 배경입니다. 매일 작업할 때 모두 외울 필요는 없습니다.

기준	이 문서에서 가져온 것
GitHub Flow	짧은 branch에서 작업하고 PR로 기본 branch에 합칩니다.
GitHub pull request reviews	PR review는 comment, approve, request changes로 품질과 지식 공유를 돕는 협업 장치입니다.
GitHub protected branches	required review, required status check, conversation resolution 같은 merge gate를 branch protection으로 설정할 수 있습니다.
GitHub issue types	Issue type은 `task`, `bug`, `feature`처럼 크게 둡니다.
GitHub issue branch	issue, branch, PR을 연결해 작업 맥락을 남깁니다.
Conventional Commits	PR title과 squash commit title에 machine-readable type을 사용합니다.
commitlint config-conventional	널리 쓰이는 확장 commit type을 참고하되, 기본 type은 작게 유지합니다.
Google Code Review Standard	Review는 완벽주의보다 code health 개선과 진행 속도의 균형을 봅니다.
Google Small CLs	작은 change set은 더 빠르고 깊게 review되며 rollback도 쉽습니다.