From 6606f21cce9b5286a6a27f30ba6999b75666c3ed Mon Sep 17 00:00:00 2001 From: esillileu <108880440+esillileu@users.noreply.github.com> Date: Mon, 12 Jan 2026 18:03:59 +0900 Subject: [PATCH] v0.0.1 Add Collaboration Agreement and Issue Template * chore: introduce dev branch for integration * chore: introduce feature/ci branch * chore: add github action flow of ci * chore: add custom command for simulate ci * chore: remove bin from gitignore to manage custom binary script * chore: introduce docs/workflow branch * docs: add commit convention * docs: add branch stratagy * docs: add PR rule * stlye: clean md style * docs: add ci coverage * docs: add issue guide * docs: add README for workflow guide * docs: unify terminology * docs: unify types * docs: add example * docs: change template header to korean * docs: add tl; dl * ops: add templates * docs: fix tl; dl * ops: fix issue type - remove quote --- .github/ISSUE_TEMPLATE/Chore.yml | 18 +++ .github/ISSUE_TEMPLATE/Docs.yml | 18 +++ .github/ISSUE_TEMPLATE/Feat.yml | 32 +++++ .github/ISSUE_TEMPLATE/Fix.yml | 39 ++++++ .github/ISSUE_TEMPLATE/Ops.yml | 18 +++ .github/ISSUE_TEMPLATE/Ref.yml | 18 +++ .github/ISSUE_TEMPLATE/Test.yml | 25 ++++ .github/pull_request_template.md | 26 ++++ .github/workflows/ci.yml | 19 +++ .gitignore | 3 +- bin/project | 25 ++++ docs/workflows/CI-coverage.md | 137 +++++++++++++++++++++ docs/workflows/README.md | 135 +++++++++++++++++++++ docs/workflows/branch-stratagy.md | 77 ++++++++++++ docs/workflows/commit-convention.md | 97 +++++++++++++++ docs/workflows/issue-guide.md | 60 +++++++++ docs/workflows/pull-request-rule.md | 181 ++++++++++++++++++++++++++++ 17 files changed, 927 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/Chore.yml create mode 100644 .github/ISSUE_TEMPLATE/Docs.yml create mode 100644 .github/ISSUE_TEMPLATE/Feat.yml create mode 100644 .github/ISSUE_TEMPLATE/Fix.yml create mode 100644 .github/ISSUE_TEMPLATE/Ops.yml create mode 100644 .github/ISSUE_TEMPLATE/Ref.yml create mode 100644 .github/ISSUE_TEMPLATE/Test.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/ci.yml create mode 100755 bin/project create mode 100644 docs/workflows/CI-coverage.md create mode 100644 docs/workflows/README.md create mode 100644 docs/workflows/branch-stratagy.md create mode 100644 docs/workflows/commit-convention.md create mode 100644 docs/workflows/issue-guide.md create mode 100644 docs/workflows/pull-request-rule.md diff --git a/.github/ISSUE_TEMPLATE/Chore.yml b/.github/ISSUE_TEMPLATE/Chore.yml new file mode 100644 index 0000000..f294bdd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Chore.yml @@ -0,0 +1,18 @@ +name: Chore - 잡일 처리 +description: 환경 설정, 파일 정리 등 기타 해야할 일들 +title: "[Chore] " +type: Chore +body: + - type: textarea + attributes: + label: 배경 및 목적 + placeholder: 작업의 필요와 목적을 설명해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 작업 목록 + placeholder: | + - [ ] A 구현 + - [ ] B 구현 diff --git a/.github/ISSUE_TEMPLATE/Docs.yml b/.github/ISSUE_TEMPLATE/Docs.yml new file mode 100644 index 0000000..6ef0306 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Docs.yml @@ -0,0 +1,18 @@ +name: Docs - 문서 수정 +description: 문서 수정 및 보완 +title: "[Docs] " +type: Docs +body: + - type: textarea + attributes: + label: 배경 및 목적 + placeholder: 문서 수정의 필요와 목적을 설명해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 작업 목록 + placeholder: | + - [ ] A 구현 + - [ ] B 구현 diff --git a/.github/ISSUE_TEMPLATE/Feat.yml b/.github/ISSUE_TEMPLATE/Feat.yml new file mode 100644 index 0000000..3250414 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Feat.yml @@ -0,0 +1,32 @@ +name: Feat - 기능 추가 +description: 새로운 기능 개발 +title: "[Feat] " +type: Feat +body: + - type: textarea + attributes: + label: 배경 및 목적 + placeholder: 기능의 필요와 목적을 설명해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 기능 명세 + placeholder: 기능의 상세 동작 내용을 기술해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 성공 기준 + placeholder: 기능이 성공적으로 구현되었음을 판단할 기준을 기술해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 작업 목록 + placeholder: | + - [ ] A 구현 + - [ ] B 구현 diff --git a/.github/ISSUE_TEMPLATE/Fix.yml b/.github/ISSUE_TEMPLATE/Fix.yml new file mode 100644 index 0000000..412086c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Fix.yml @@ -0,0 +1,39 @@ +name: Fix - 버그 수정 +description: 버그 상황을 재현하고 수정 +title: "[Fix] " +type: Fix +body: + - type: textarea + attributes: + label: 발생 환경 + placeholder: 버그가 발생한 환경(운영체제, 브라우저 등)을 기술해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 재현 단계 + placeholder: 버그를 재현하기 위한 구체적인 단계를 기술해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 버그 발생시 결과 + placeholder: 버그가 발생했을 때의 구체적인 결과를 기술해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 예상 결과 + placeholder: 버그가 없을 때 기대되는 정상적인 결과를 기술해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 작업 목록 + placeholder: | + - [ ] A 구현 + - [ ] B 구현 diff --git a/.github/ISSUE_TEMPLATE/Ops.yml b/.github/ISSUE_TEMPLATE/Ops.yml new file mode 100644 index 0000000..a0a1aa0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Ops.yml @@ -0,0 +1,18 @@ +name: Ops - 운영 작업 +description: 배포, 자동화 등 운영 관련 작업 +title: "[Ops] " +type: Ops +body: + - type: textarea + attributes: + label: 배경 및 목적 + placeholder: 작업의 필요와 목적을 설명해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 작업 목록 + placeholder: | + - [ ] A 구현 + - [ ] B 구현 diff --git a/.github/ISSUE_TEMPLATE/Ref.yml b/.github/ISSUE_TEMPLATE/Ref.yml new file mode 100644 index 0000000..9de0610 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Ref.yml @@ -0,0 +1,18 @@ +name: Ref - 리팩토링 +description: 코드 스타일, 이름변경, 구조 변경 등 기능 변경이 없는 코드작업 +title: "[Ref] " +type: Ref +body: + - type: textarea + attributes: + label: 배경 및 목적 + placeholder: 작업의 필요와 목적을 설명해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 작업 목록 + placeholder: | + - [ ] A 구현 + - [ ] B 구현 diff --git a/.github/ISSUE_TEMPLATE/Test.yml b/.github/ISSUE_TEMPLATE/Test.yml new file mode 100644 index 0000000..248167d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Test.yml @@ -0,0 +1,25 @@ +name: Test - 테스트 +description: 기능, 시스템의 테스트 작업 +title: "[Test] " +type: Test +body: + - type: textarea + attributes: + label: 테스트 대상 + placeholder: 테스트 대상(기능, 시스템 등)을 설명해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 테스트 방법 및 로직 + placeholder: 테스트를 수행할 방법과 로직을 기술해주세요. + validations: + required: true + + - type: textarea + attributes: + label: 작업 목록 + placeholder: | + - [ ] A 구현 + - [ ] B 구현 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..79d4418 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +## 관련 이슈 + + + +- 이슈 번호 작성 + +## 변경 사항 + +- 이 PR에서 변경된 내용을 간단히 작성 + +## 배경 + +- 왜 이 변경이 필요한지 +- 관련 논의나 이슈가 있다면 링크 + +## 구현 상세 + +- 주요 구현 방식 +- 리뷰 시 봐주면 좋은 포인트 + +## 체크리스트 + +- [ ] 로컬에서 정상 동작 확인 +- [ ] 테스트 코드 추가/수정 (해당 시) +- [ ] 문서 업데이트 (해당 시) +- [ ] 불필요한 코드/주석 제거 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..90ee31a --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,19 @@ +name: Markdown Lint + +on: + pull_request: + branches: [dev] + push: + branches: [dev] + +jobs: + markdownlint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Run markdownlint + uses: DavidAnson/markdownlint-cli2-action@v16 + with: + globs: | + **/*.md diff --git a/.gitignore b/.gitignore index cc76af5..eaea35c 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,6 @@ Thumbs.db *.swo # 빌드 결과물 및 바이너리 무시 -bin/ build/ dist/ *.o @@ -26,3 +25,5 @@ logs/ tmp/ temp/ *.tmp + +.envrc diff --git a/bin/project b/bin/project new file mode 100755 index 0000000..8d747e2 --- /dev/null +++ b/bin/project @@ -0,0 +1,25 @@ +#!/bin/bash + +# Project Utility CLI +# Usage: project +CTX=act + +if ! docker context inspect "$CTX" >/dev/null 2>&1; then + docker context create "$CTX" +fi + +COMMAND=$1 +shift + +case "$COMMAND" in + ci) + echo "Simulating Dev CI (act)..." + docker context use "$CTX" + act pull_request -W .github/workflows/ci.yml --container-architecture linux/amd64 + docker context use default + ;; + *) + echo "Usage: project {ci}" + exit 1 + ;; +esac diff --git a/docs/workflows/CI-coverage.md b/docs/workflows/CI-coverage.md new file mode 100644 index 0000000..891b01e --- /dev/null +++ b/docs/workflows/CI-coverage.md @@ -0,0 +1,137 @@ +# CI Scope Guide + +이 문서는 본 프로젝트에서 사용하는 **기본 CI 범위와 흐름**를 안내합니다. +본 프로젝트 전반에서 공통으로 사용하는 CI 흐름을 설명하기 위한 문서입니다. +과도한 자동화보다는 협업 안정성과 확인 흐름을 명확히 하는 것을 목표로 합니다. + +--- + +## 3줄 요약 + +- 각 단계에서 테스트 진행됨: 로컬 커밋 (자동) > 로컬 빌드(수동) > dev 병합(자동) > main 병합(수동) +- 통과 못 하는건 개인 잘못 아님. 자잘한건 애초에 자동으로 수정해줌 +- 로컬에서 미리 시뮬레이션 돌리면 실패 확률 줄어듬 + +--- + +## 1. CI 운영의 기본 방향 + +- CI는 통과를 위한 장벽이 아니라, 문제를 조기에 발견하고 공통 기준을 제공하기 위한 보조 수단입니다. +- 로컬 → dev 병합 → main 병합 단계로 갈수록 확인 범위를 점진적으로 강화합니다. +- 초기 단계에서는 문서 품질과 협업 안정성에 필요한 최소 범위만 자동화합니다. +- 모든 단계는 팀원이 쉽게 이해하고 재현할 수 있는 구성을 지향합니다. + +--- + +## 2. 단계별 CI 흐름 개요 + +```text +Local (Pre-commit) + └─ 개인 작업 중 즉시 확인 + +PR → dev + └─ 팀 단위 통합 전 기본 검증 + +PR → main + └─ 기준선 확정 전 최종 검증 +``` + +--- + +## 3. 단계별 상세 설명 + +### 3.1. 로컬 커밋 단계: Pre-commit 기반 확인 + +로컬 단계에서는 각 팀원이 커밋 전에 최소한의 품질 검사를 수행하도록 유도합니다. +이 단계의 목적은 CI 실패를 사전에 줄이고, 반복적인 수정 비용을 낮추는 것입니다. + +#### 3.1.1 적용 시점 + +- `git commit` 실행 시 자동으로 동작합니다. +- 직접 실행하여 수동 점검 용도로 사용할 수도 있습니다. + +#### 3.1.2 확인 범위 + +- 언어 기본 문법 및 스타일 검사 +- 불필요한 공백, 줄 끝 공백, 파일 끝 개행 여부 확인 +- 명백한 형식 오류 위주로만 검사합니다. + +> 로컬 pre-commit 단계에서는 규칙 위반을 엄격히 막기보다는, 빠른 피드백 제공을 우선합니다. +> 커밋 실행시 취소될 수 있습니다. 이 경우 출력 로그에 어디가 문제가 되는지 나오니, 해당 부분을 수정해주세요 +> 기본적으로는 자동으로 고치도록 되어있습니다. 다시 파일을 추가해서 커밋하면 됩니다. + +--- + +### 3.2 로컬 빌드 단계: 수동 테스트 + +이 단계의 목적은 빌드 실패로 인한 작업 중단과 디버깅 문제를 최소화하기 위함입니다. +해당 단계는 개발 담당자에게 그 권한과 책임이 전적으로 위임됩니다. 즉, 권장하나 강제하지 않습니다. + +#### 3.2.2 확인 범위 + +- 로컬 단계에서 브랜치를 최종적으로 푸시하고 PR을 올리기 전 수동으로 테스트합니다. + +#### 3.2.2 적용시점 + +- PR을 올리기 전, 담당자가 로컬에서 수동으로 테스트합니다. +- 구현 기능의 세부 기능들에 대한 유닛테스트를 진행합니다. +- 빌드 및 헬스 체크, 기본 기능이 동작하는지 스크립트를 통해 검증합니다. + +--- + +### 3.3. PR → dev 단계: 통합 전 기본 검증 + +dev 브랜치는 팀 작업이 처음으로 합쳐지는 통합 지점입니다. +이 단계의 CI는 여러 사람의 변경 사항이 함께 들어와도 문제없이 유지되는지를 확인하는 데 목적이 있습니다. + +#### 3.3.1. 적용 시점 + +- 모든 작업 브랜치(`feat/*`, `fix/*` 등)에서 `dev` 브랜치로 PR이 생성되거나 업데이트될 때 Github Action으로 실행됩니다. +- PR 열리자마자 머지하면 가끔 스킵되기도 하니 반드시 열고 기다려 주세요. +- 로컬에서 act를 통해 시뮬레이션 해볼 수 있습니다. 레포별 bin/project에 해당 로직을 구현해둘 예정입니다. + +#### 3.3.2. 확인 범위 + +- 로컬 pre-commit 단계에서 수행하는 검사 전체 +- 세부 기능별 유닛 테스트 + +> dev 단계 CI는 팀 내부 합의를 기준으로 한 "기본 품질선"을 유지하는 역할을 합니다. + +--- + +### 3.4. PR → main 단계: 기준선 확정 검증 + +main 브랜치는 외부 공개 및 장기 기준선 역할을 하는 브랜치입니다. +따라서 이 단계에서는 가장 안정적인 상태인지 확인하는 것을 목표로 합니다. + +#### 3.4.1 적용 시점 + +- dev 브랜치에서 main 브랜치로 PR이 생성되거나 업데이트될 때 Github Action으로 실행됩니다. +- PR 열리자마자 머지하면 가끔 스킵되기도 하니 반드시 열고 기다려 주세요. +- 로컬에서 act를 통해 시뮬레이션 해볼 수 있습니다. 레포별 bin/project에 해당 로직을 구현해둘 예정입니다. + +### 5.2 확인 범위 + +- dev 단계 CI에서 수행하는 검사 전체 +- 빌드 또는 렌더링에 영향을 주는 치명적 오류 여부 확인 +- 필수 파일(README, 주요 안내 문서 등) 누락 여부 확인 +- 컴포넌트별 유닛 테스트 +- 컴포넌트별 통신 테스트 +- 통합 End 2 End 테스트 + +> main 단계 CI는 실패 시 병합을 중단시키는 최종 안전장치 역할을 합니다. + +--- + +## 6. CI 실패 시 대응 원칙 + +- CI 실패는 개인의 실수가 아니라, 흐름 상 발견된 문제로 간주합니다. +- 실패 원인을 먼저 확인하고, 필요한 경우 커밋을 추가하여 수정합니다. +- 히스토리를 수정하기 위한 rebase나 force push는 shared 브랜치(dev, main)에서는 사용하지 않습니다. + +--- + +## 7. 적용 범위 및 확장에 대한 안내 + +- 본 문서의 CI 범위는 프로젝트 **전 레포(Main/Core/FE/BE/Ops)에 공통으로 적용되는 기본 기준**입니다. +- 각 구현 레포(Core/FE/BE/Ops)는 이 기준을 바탕으로, 필요에 따라 추가적인 CI 단계를 정의할 수 있습니다. diff --git a/docs/workflows/README.md b/docs/workflows/README.md new file mode 100644 index 0000000..42d7482 --- /dev/null +++ b/docs/workflows/README.md @@ -0,0 +1,135 @@ +# 신규 팀원을 위한 개발 워크플로우 안내 + +이 문서는 프로젝트에 새로 참여한 팀원이 작업 흐름 전반을 이해하고 빠르게 적응할 수 있도록 돕기 위한 통합 가이드입니다. 아래 절차만 따라하면 기본적인 개발 과정에 참여할 수 있습니다. + +더 상세한 규칙은 아래 문서들을 참고할 수 있습니다. + +- [브랜치 전략 (Branching Strategy)](./branch-stratagy.md) +- [커밋 컨벤션 (Commit Convention)](./commit-convention.md) +- [PR 규칙 (Pull Request Rules)](./pull-request-rule.md) +- [이슈 작성 가이드 (Issue Creation Guide)](./issue-guide.md) +- [CI 범위 안내 (CI Scope Guide)](./CI-coverage.md) + +--- + +## 빠른 참조 (Workflow Cheatsheet) + +이 문서는 개발 과정 각 단계에서 필요한 핵심 규칙, 형식, 명령어를 요약한 빠른 참조 문서입니다. + +| 단계 | 항목 | 내용 | 예시 | +| :------------ | :------------- | :--------------------------------------------------------------------- | :--------------------------------------- | +| **1. 이슈** | 제목 형식 | `[타입] <내용 요약>` (타입 첫 글자 대문자) | `[Feat] 소셜 로그인 기능 추가` | +| | 타입 | `Feat`, `Fix`, `Docs`, `Refactor`, `Test`, `Chore`, `Ops` | | +| | 템플릿 사용 | `issue-guide.md` 참고 | | +| **2. 브랜치** | 이름 형식 | `타입/이슈번호-이름` (타입은 소문자) | `feat/11-new-login-page` | +| | 타입 | `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ops` (+ `hotfix`) | | +| | 분기 대상 | `dev` (단, `hotfix`는 `main`) | | +| | 타입 매핑 | `[Fix]` 이슈 → `fix/` 브랜치. 나머지는 이름 일치. | | +| | 생성 명령어 | `git checkout -b <브랜치명>` | `git checkout -b feat/11-new-login-page` | +| **3. 커밋** | 메시지 형식 | `타입: <요약>` (타입은 소문자) | `feat: add login page structure` | +| | 타입 | `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ops` | | +| | 명령어 | `git commit -m "<메시지>"` | | +| **4. PR** | 제목 형식 | `타입: <요약>` | `feat: add login page structure` | +| | 대상 브랜치 | `dev` (단, `hotfix`는 `main`) | | +| | 이슈 연결 | 본문 하단 `Closes`/`Fixes` 키워드 사용 | `Closes #11` | +| | 푸시 명령어 | `git push origin <브랜치명>` | `git push origin feat/11-new-login-page` | +| **5. 원칙** | 셀프 머지 | **금지** | | +| | CI 실패 | **리뷰 요청 금지** | | +| **6. 동기화** | `dev` 최신화 | `git checkout dev && git pull origin dev` | | +| | 내 브랜치 반영 | `git merge dev` | `git merge dev` | + +--- + +## 전체 워크플로우 요약 + +우리 팀의 기본적인 개발 작업은 아래와 같은 흐름으로 진행됩니다. + +> **1. 이슈 확인/생성 → 2. 브랜치 생성 → 3. 로컬 개발 및 커밋 → 4. PR 생성 → 5. 리뷰 및 논의 → 6. 병합 → 7. 동기화 및 정리** + +--- + +## 단계별 상세 가이드 + +### 1단계: 작업 시작 - 이슈(Issue) 확인 및 생성 + +- 모든 작업은 **이슈(Issue)** 에서 시작합니다. 이슈는 작업의 목적과 내용을 명확히 하는 역할을 합니다. +- 개발을 시작하기 전, GitHub 저장소의 `Issues` 탭에서 내가 맡을 작업에 대한 이슈가 있는지 확인합니다. +- 만약 이슈가 없다면, [이슈 작성 가이드](./issue-guide.md)에 따라 `[Feat]`, `[Fix]` 등 타입에 맞는 새로운 이슈를 생성합니다. + +### 2단계: 브랜치(Branch) 생성 + +- 이슈를 기반으로 로컬에서 개발을 진행할 브랜치를 생성합니다. 브랜치 타입은 [브랜치 전략](./branch-stratagy.md)의 매핑 규칙을 따릅니다. +- 항상 최신 상태의 `dev` 브랜치에서 새로운 브랜치를 분기합니다. + +```sh +# 1. 로컬 dev 브랜치로 이동 +git checkout dev + +# 2. 원격 저장소의 최신 내용을 dev 브랜치에 반영 +git pull origin dev + +# 3. 새로운 작업 브랜치 생성 및 이동 (규칙: 타입/이슈번호-이름) +# 예시: [Feat] 타입 이슈 #11에 대한 작업 +git checkout -b feat/11-new-login-page +``` + +### 3단계: 로컬 개발 및 커밋(Commit) + +- 생성한 브랜치에서 코드를 수정하거나 새로운 파일을 추가하며 기능을 개발합니다. +- 커밋 메시지는 [커밋 컨벤션](./commit-convention.md)을 반드시 따릅니다. + +```sh +# 예시: feat/11-new-login-page 브랜치에서의 커밋 +git commit -m "feat: add user login form" +``` + +- **Pre-commit 사용**: 우리 프로젝트는 커밋 시점에 코드 스타일을 자동으로 검사합니다. **최초 설정은 [환경 설정 문서](../setup.md)를 참고하여 `pre-commit install`을 먼저 실행해야 합니다.** + +### 4단계: Pull Request(PR) 생성 + +- 로컬 개발이 완료되면, 변경 사항을 원격 저장소에 푸시(push)하고 `dev` 브랜치로 **Pull Request(PR)** 를 생성합니다. +- PR 제목과 본문은 [PR 규칙](./pull-request-rule.md)에 따라 상세히 작성합니다. +- 관련 이슈가 있다면 PR 본문 하단에 `Closes #[이슈번호]` 와 같이 연결합니다. + +```sh +# 1. 내 작업 브랜치를 원격 저장소에 푸시 +git push origin feat/11-new-login-page +``` + +### 5단계: 리뷰 및 논의(Review & Discussion) + +- PR을 생성하면 CI(자동 검증)가 실행됩니다. **CI가 실패한 상태에서는 리뷰를 요청하지 않는 것을 원칙으로 합니다.** +- 리뷰어의 의견에 따라 코드를 수정해야 할 경우, 로컬 브랜치에서 추가 커밋을 하고 다시 푸시하면 PR에 자동으로 반영됩니다. + +### 6단계: 병합(Merge) + +- PR이 최종 승인되면, 담당자가 PR을 `dev` 브랜치에 병합합니다. **기본적으로 PR 작성자 본인이 직접 병합하지 않습니다.** +- 병합이 완료되면 내가 작성한 코드가 팀의 공용 브랜치에 공식적으로 반영됩니다. + +### 7단계: 동기화 및 정리(Sync & Cleanup) + +- 작업 브랜치 병합 후에는 뒷정리가 필요합니다. + +1. **로컬 브랜치 동기화**: 진행 중인 다른 작업 브랜치가 있다면, 최신화된 `dev` 브랜치의 내용을 가져와 반영합니다. + + ```sh + # 1. 로컬 dev 브랜치로 이동 후 최신화 + git checkout dev + git pull origin dev + + # 2. (만약 다른 작업 브랜치가 있다면) 해당 브랜치로 이동 후 dev 병합 + git checkout fix/22-another-bug + git merge dev + ``` + +2. **작업 완료 브랜치 삭제**: 병합이 완료된 브랜치는 삭제합니다. + + ```sh + # 로컬에서 작업 브랜치 삭제 + git branch -d feat/11-new-login-page + + # 원격 저장소에서 작업 브랜치 삭제 + git push origin --delete feat/11-new-login-page + ``` + +--- diff --git a/docs/workflows/branch-stratagy.md b/docs/workflows/branch-stratagy.md new file mode 100644 index 0000000..146dbb9 --- /dev/null +++ b/docs/workflows/branch-stratagy.md @@ -0,0 +1,77 @@ +# 브랜치 전략 (Branching Strategy) + +이 문서는 프로젝트 전반에서 사용하는 브랜치 명명법과 작업 흐름의 핵심 규칙을 정의합니다. + +--- + +## 0. 3줄 요약 + +- 작업 단위는 **이슈**이며, 모든 브랜치는 이슈를 기반으로 생성합니다. +- 브랜치는 `feat`, `fix`, `docs` 등 **7가지 작업 브랜치**와 예외적인 **`hotfix` 브랜치**로 나뉩니다. +- `dev` 브랜치를 중심으로 작업을 통합하며, `main` 브랜치는 안정 버전으로 관리합니다. + +```text +# Merge Flow (병합 흐름) +main <-[ PR | Squash ]- dev <--[ PR | Merge ]-- 작업 브랜치: ex)feat/{issue-number}-* + +# Sync Flow (동기화 흐름) +main --[ PR | Merge ]-> dev --[ local merge ]-> 작업 브랜치: ex)feat/{issue-number}-* + +# Hotfix Flow +main <-[ PR | Squash ]-------------- hotfix + └-----[ PR | Merge ]--> dev +``` + +--- + +## 1. 핵심 원칙 + +- **이슈 기반 개발**: 모든 브랜치는 특정 이슈를 해결하기 위해 생성합니다. 브랜치 이름에는 반드시 해당 **이슈 번호**가 포함되어야 합니다. +- **1 브랜치, 1인 담당**: 하나의 작업 브랜치는 한 사람이 담당하여 작업하는 것을 원칙으로 합니다. (공동 작업 시에는 `-co` 접미사를 사용) +- **`dev` 브랜치 중심**: 모든 작업 브랜치는 `dev`에서 시작하여 `dev`로 병합하는 것을 원칙으로 합니다. (`hotfix` 제외) +- **PR 기반 병합**: `main`, `dev` 브랜치에는 직접 커밋하지 않으며, 모든 변경사항은 Pull Request(PR)를 통해서만 병합합니다. + +--- + +## 2. 브랜치 종류 + +### 2.1. 기본 브랜치 + +- **main**: 항상 배포 가능한 가장 안정적인 상태의 브랜치입니다. `dev` 브랜치의 내용이 충분히 검증된 후, 버전 단위로 병합됩니다. +- **dev**: 개발된 기능들이 통합되고 검증되는 브랜치입니다. 모든 작업 브랜치가 이곳으로 병합됩니다. + +### 2.2. 작업 브랜치 (Working Branches) + +작업 브랜치는 아래 7가지 타입으로 나뉩니다. 브랜치 타입은 커밋 메시지 타입과 동일합니다. + +| 브랜치 타입 | 목적 | 예시 | +| :---------- | :----------------------- | :-------------------------------- | +| `feat` | 새로운 기능 개발 | `feat/11-login-page` | +| `fix` | 버그 수정 | `fix/22-login-error` | +| `docs` | 문서 추가 및 수정 | `docs/31-update-readme` | +| `refactor` | 코드 리팩토링 | `refactor/45-simplify-user-model` | +| `test` | 테스트 코드 추가 및 수정 | `test/52-add-login-test` | +| `chore` | 빌드, 설정 등 기타 잡일 | `chore/66-update-dependencies` | +| `ops` | DevOps, 인프라, 배포 | `ops/71-setup-cicd` | + +### 2.3. 예외 브랜치 (Exception Branch) + +- **`hotfix/{issue-number}-{name}`** + - **목적**: `main` 브랜치에서 발생한 치명적인 버그를 긴급하게 수정할 때만 사용합니다. + - **분기 대상**: `main` + - **병합 대상**: `main` 브랜치로 직접 PR 및 병합 후, 반드시 `dev` 브랜치에도 변경 내용을 동기화해야 합니다. + - **예시**: `hotfix/23-critical-error` + +--- + +## 3. 병합 규칙 + +- **`dev` 브랜치로 병합 시**: **Merge Commit** (`--no-ff`) 방식을 사용하여, 작업 히스토리를 모두 `dev`에 기록하는 것을 원칙으로 합니다. +- **`main` 브랜치로 병합 시**: **Squash and Merge** 방식을 사용하여, `dev`의 기능 개발 이력을 하나의 버전 커밋으로 묶어 `main`에 반영합니다. + +--- + +## 4. 히스토리 관리 + +- `main`, `dev`와 같이 여러 사람이 함께 사용하는 공유 브랜치에서는 `rebase`나 `push --force` 등 히스토리를 변경하는 명령을 절대 사용하지 않습니다. +- 히스토리 관리는 개인의 작업 브랜치 내에서만 자유롭게 할 수 있습니다. diff --git a/docs/workflows/commit-convention.md b/docs/workflows/commit-convention.md new file mode 100644 index 0000000..0b34424 --- /dev/null +++ b/docs/workflows/commit-convention.md @@ -0,0 +1,97 @@ +# Commit Convention + +이 문서는 프로젝트 전반에서 사용하는 커밋 메시지 규칙을 정의합니다. +모든 커밋은 아래 규칙을 따르는 것을 원칙으로 합니다. + +--- + +## 0. 3줄 요약 + +- 커밋메시지는 작업의 의미단위별로 나눠서 7개 타입중에 할당하고, 상세 내용은 소문자로 기록하기 +- 브랜치에 첫 커밋은 작업내용 없는 빈 커밋 `git commit --allow-empty -m "chore: introduce {branch-name} branch"` +- 개인 브랜치에서는 과거 커밋 수정 자유, 공유 브랜치에서는 절대 안됨 + +--- + +## 1. 기본 형식 + +```text +: +``` + +- 한 줄로 작성합니다. +- 영어를 사용합니다. +- summary는 변경 내용을 간결하게 설명합니다. +- 마침표(`.`)는 사용하지 않습니다. + +--- + +## 2. 사용 가능한 타입 + +아래 타입만 사용합니다. + +- **feat**: 새로운 기능 추가 (로직 추가) +- **fix**: 버그 수정 +- **refactor**: 기능 변경 없는 코드 구조 개선 (로직이 변경 될 수 있으나 입출력 동일) +- **docs**: 문서 추가 또는 수정 +- **test**: 테스트 코드 추가 또는 수정 +- **chore**: 설정, 규칙, 도구, 브랜치 시작, 기타 잡일 +- **ops**: DevOps, 배포, 인프라 관련 작업 + +> 브랜치, 설정 관련 작업은 `chore`를, 배포/인프라 관련 작업은 `ops`를 사용합니다. + +--- + +## 3. 예시 + +```text +chore: add initial collaboration rules +docs: add environment setup guide +feat: implement rule graph builder +fix: handle empty scenario input +``` + +--- + +## 4. 권장 규칙 + +- 한 커밋은 하나의 논리적인 변경만 포함합니다. +- 서로 다른 목적의 변경은 커밋을 분리합니다. +- 의미 없는 커밋 메시지는 지양합니다. + +--- + +## 5. 금지 사항 + +아래와 같은 메시지는 사용하지 않습니다. + +```text +init +update +fix bug +작업함 +``` + +> 위와 같은 메시지는 변경 내용을 추적하기 어렵게 만듭니다. + +--- + +## 6. 예외 + +브랜치의 첫 커밋에 한해 아래 메시지를 허용합니다. 아래 커멘드로 변경 사항 없는 커밋을 만들어 주세요. `{branch-name}`에 브랜치 이름을 넣어주세요. + +```text +chore: introduce {branch-name} branch +``` + +```sh +git commit --allow-empty -m "chore: introduce {branch-name} branch" +``` + +## 7. 히스토리 수정(리라이트) 원칙 + +- 원격(공유) 브랜치(`main`, `dev`)에서는 rebase, force push 등 히스토리 수정을 하지 않습니다. +- 실수한 커밋은 새로운 커밋으로 수정하거나, PR에서 정리(squash)합니다. +- 예외: 개인 작업 브랜치에서는 rebase, force push 사용 가능합니다. + +--- diff --git a/docs/workflows/issue-guide.md b/docs/workflows/issue-guide.md new file mode 100644 index 0000000..f3aae26 --- /dev/null +++ b/docs/workflows/issue-guide.md @@ -0,0 +1,60 @@ +# 이슈 작성 가이드 (Issue Creation Guide) + +이 문서는 프로젝트에서 사용하는 이슈(Issue) 작성 규칙을 안내합니다. +모든 작업은 이슈 생성을 통해 공유하고 추적하는 것을 원칙으로 합니다. + +--- + +## 0. 3줄 요약 + +- 무슨 작업이든 이슈에서 시작 - 이슈를 만들고 브랜치를 만들기 or 있는 이슈중에 선택해 브랜치 만들기 +- 작업 타입 7개중 하나 고른 뒤, 템플릿 내용 성실하게 작성하기 +- 이슈에서 정의한 작업이 다 끝나면, PR 올리고 리뷰 받아서 닫기 + +--- + +## 1. 이슈 작성 기본 원칙 + +- **7가지 타입 사용**: 이슈는 `Feat`, `Fix`, `Docs`, `Refactor`, `Test`, `Chore`, `Ops` 중 하나의 타입을 가집니다. +- **제목 형식**: 제목은 `[타입] <내용 요약>` 형식을 따릅니다. 타입의 첫 글자는 대문자로 작성합니다. + - 예시: `[Feat] 소셜 로그인 기능 추가` +- **담당자(Assignee) 및 레이블(Label) 지정**: 이슈 생성 시 담당자와 관련 레이블을 반드시 지정합니다. 레이블은 이슈 타입과 동일하게 소문자로 지정합니다. (e.g., `feat`, `fix`) + +--- + +## 2. 이슈 타입별 가이드 + +### `[Feat]` + +- **목적**: 사용자에게 새로운 가치를 제공하는 기능 추가 +- **본문**: 아래 템플릿을 사용하여 배경, 기능 명세, 성공 기준을 구체적으로 작성합니다. + +### `[Fix]` + +- **목적**: 잘못된 동작을 수정하는 버그 수정 +- **본문**: 아래 템플릿을 사용하여 버그 상황을 명확히 설명합니다. + +### `[Docs]` + +- **목적**: 문서의 추가, 수정, 삭제 +- **본문**: 변경이 필요한 문서와 수정 내용을 자유롭게 기술합니다. + +### `[Refactor]` + +- **목적**: 외부 동작 변경 없이 코드 구조를 개선 +- **본문**: 리팩토링의 대상과 그 이유, 기대 효과를 중심으로 작성합니다. + +### `[Test]` + +- **목적**: 테스트 코드의 추가 및 수정 +- **본문**: 어떤 부분에 대한 테스트를 추가/수정할 것인지 구체적으로 작성합니다. + +### `[Chore]` + +- **목적**: 빌드, 설정, 의존성 관리 등 위 타입에 속하지 않는 기타 잡일 +- **본문**: 작업의 목표와 할 일 목록(To-Do List)을 중심으로 작성합니다. + +### `[Ops]` + +- **목적**: CI/CD, 배포, 인프라 등 DevOps 관련 작업 +- **본문**: 작업의 목표와 필요한 절차를 중심으로 작성합니다. diff --git a/docs/workflows/pull-request-rule.md b/docs/workflows/pull-request-rule.md new file mode 100644 index 0000000..0fc19ec --- /dev/null +++ b/docs/workflows/pull-request-rule.md @@ -0,0 +1,181 @@ +# Pull Request Rules + +이 문서는 프로젝트 전반에서 사용하는 Pull Request(PR) 관련 기준을 정리한 안내 문서입니다. +프로젝트의 변경 사항은 PR을 통해 공유·검토·병합하는 흐름을 기본으로 합니다. + +PR은 단순한 병합 요청보다는, **변경 내용과 그 배경을 함께 남기는 기록 단위**로 활용합니다. + +--- + +## 0. PR의 목적 + +PR은 다음과 같은 역할을 기대하고 있습니다. + +- 변경 내용의 의도와 범위를 한눈에 파악할 수 있을 것 +- 별도 설명 없이도 리뷰어가 맥락을 이해할 수 있을 것 +- 이후 변경 이력을 되돌아볼 때 참고 자료로 활용할 수 있을 것 + +--- + +## 1. PR 생성 기본 가이드 + +- 변경 사항은 PR을 통해 병합하는 방식을 사용합니다. +- 직접 커밋 후 바로 병합하는 방식은 사용하지 않습니다. +- PR은 하나의 작업 단위를 기준으로 생성합니다. +- 하나의 PR에는 하나의 목적만 담는 것을 권장합니다. + +### 예시 + +- **권장하지 않는 경우** + +> A 기능 추가, B 문서 수정, C 리팩터링을 하나의 PR로 묶는 경우 + +- **권장하는 경우** + +> A 기능 PR / B 문서 PR / C 리팩터링 PR로 분리 + +--- + +## 2. PR 대상 브랜치 안내 + +모든 작업 브랜치는 `dev` 브랜치로 PR을 생성합니다. `hotfix`만이 예외적으로 `main` 브랜치로 PR을 생성합니다. + +| 작업 브랜치 타입 | PR 대상 | +| :--------------- | :--------- | +| `feat/*` | `dev` | +| `fix/*` | `dev` | +| `docs/*` | `dev` | +| `refactor/*` | `dev` | +| `test/*` | `dev` | +| `chore/*` | `dev` | +| `ops/*` | `dev` | +| **`hotfix/*`** | **`main`** | +| `dev` | `main` | + +- 모든 작업 브랜치는 `dev` 브랜치를 통해 통합합니다. +- `main` 브랜치로의 직접 PR은 `hotfix` 브랜치에서만 사용합니다. + +--- + +## 3. PR 제목 작성 가이드 + +PR 제목은 [커밋 컨벤션](./commit-convention.md)과 동일한 형식을 사용합니다. + +```text +: +``` + +예시: + +```text +feat: add rule graph base structure +docs: add branching strategy document +fix: resolve type error in parser(#22) +``` + +### 이슈가 있는 경우 + +- 관련 이슈가 있다면 제목에 이슈 번호를 함께 표기합니다. + +```text +fix: resolve type error in parser(#22) +``` + +### 이슈 연결 키워드 사용 + +PR이 해결하는 이슈가 있다면, 본문 최하단에 관련 키워드를 사용해 이슈 번호를 명시합니다. 이 규칙을 통해 PR이 병합될 때 연결된 이슈가 **자동으로 종료(close)**되어 작업 추적을 용이하게 합니다. + +- **목적별 키워드:** + + - `feat`, `refactor` 등 기능 구현 및 개선: `Closes #{issue-number}` + - `fix`, `hotfix` 등 버그 수정: `Fixes #{issue-number}` + - `docs` 등 기타 작업 완료: `Closes #{issue-number}` + +- **작성 위치:** PR 본문 내용의 가장 마지막 줄에 추가합니다. + +- **예시:** + +```text + +Fixes #22 +``` + +--- + +## 4. PR 본문 작성 가이드 + +- 간단한 PR이라도 배경 항목은 작성하는 것을 권장합니다. +- 코드가 아닌 경우 구현 상세와 체크리스트는 생략해도 괜찮습니다. + +--- + +## 5. 리뷰 관련 안내 + +- **CI 실패 시 리뷰 요청 금지**: PR 생성 시 실행되는 CI가 실패한 상태에서는 리뷰를 요청하지 않는 것을 원칙으로 합니다. CI를 우선 통과시켜주세요. +- **Self-Merge 금지**: 기본적으로 PR 작성자 본인이 직접 병합하지 않습니다. +- **최소 1명 이상 리뷰**: `dev`, `main` 브랜치로 병합되는 모든 PR은 최소 1명 이상의 리뷰어에게 승인(`Approve`)받아야 합니다. + +리뷰에서는 다음과 같은 부분을 함께 살펴봅니다. + +- 변경 범위가 PR 목적과 잘 맞는지 +- 브랜치 및 커밋 규칙을 따르고 있는지 +- 의도와 무관한 변경이 섞이지 않았는지 + +리뷰는 정답 여부보다는, **변경 내용을 이해하기 쉬운지 확인하는 과정**으로 생각합니다. + +--- + +## 6. 병합 방식 안내 + +브랜치 성격에 따라 병합 방식을 다음과 같이 사용합니다. + +- dev 브랜치 병합 + + - 기본적으로 Merge Commit을 사용합니다. + - squash를 사용하는 경우, PR 본문에 간단한 사유를 남깁니다. + +- main 브랜치 병합 + + - Squash Merge 방식을 사용합니다. + - 병합 단위는 마이너 버전 기준을 따릅니다. + +--- + +## 7. PR 크기 가이드 + +PR은 가능한 한 작게 유지하는 편이 리뷰와 추적에 도움이 됩니다. + +권장 기준: + +- 코드 변경 PR: 약 300줄 이내 +- 문서 PR: 하나의 주제 단위 + +변경 범위가 큰 경우에는 PR을 나누거나, 사전에 이슈로 맥락을 공유하는 방식을 고려합니다. + +--- + +## 8. 병합 이후 참고 사항 + +- PR 병합 후에는 해당 작업 브랜치를 정리합니다. +- dev 또는 main 병합 이후에는 로컬 브랜치 동기화를 권장합니다. +- 이미 병합된 PR에 추가 커밋을 이어서 쌓기보다는, 필요 시 새로운 PR을 생성합니다. + +--- + +## 9. 참고하지 않는 방식 + +다음과 같은 경우는 지양합니다. + +- 리뷰 없이 병합하는 경우 +- 목적이 명확하지 않은 PR +- 의미를 알기 어려운 제목 (예: update, fix stuff 등) +- 하나의 PR에 여러 목적을 함께 담는 경우 +- main / dev 브랜치의 히스토리를 직접 수정하는 경우 + +--- + +## 10. 정리 + +- PR은 변경 이력을 남기는 기록입니다. +- PR 하나만 보아도 무엇을, 왜, 어떻게 변경했는지 알 수 있으면 좋습니다. +- 이해하기 쉬운 PR이 협업에 도움이 됩니다.