diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..15fe8a0 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,79 @@ +name: CI + +on: + pull_request: + branches: [main] + push: + branches: [main] + +permissions: + contents: read + pull-requests: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + lint: + name: Lint (pre-commit) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + + - uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Install pre-commit + run: pip install pre-commit + + - name: Run pre-commit + run: pre-commit run --all-files --show-diff-on-failure --color always + + pr-title: + name: Lint PR title + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + permissions: + pull-requests: read + steps: + - uses: amannn/action-semantic-pull-request@v5 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + types: | + feat + fix + docs + refactor + test + chore + style + ci + build + perf + scopes: | + meta + adr + research + product + design + arch + agents + backend + frontend + eval + infra + requireScope: false + subjectPattern: "^[a-z].+[^.]$" + subjectPatternError: | + PR title subject must start with a lowercase letter, + be non-empty, and not end with a period. diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..0edec91 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,24 @@ +# markdownlint rules — see https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +default: true + +# Line length — we use tables and long prose; rely on editor soft-wrap +MD013: false + +# Inline HTML — allowed (mermaid, details, badges) +MD033: false + +# First line should be H1 — we use YAML frontmatter first +MD041: false + +# Duplicate heading text allowed under different parent headings +MD024: + siblings_only: true + +# Bare URLs allowed (footnotes/references) +MD034: false + +# Bold-as-heading allowed for emphasis within lists +MD036: false + +# Allow inline code blocks without language in quick notes +MD040: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..e8870bc --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,40 @@ +# Synapse — pre-commit hooks +# Install: pipx install pre-commit && pre-commit install && pre-commit install --hook-type commit-msg +# Update: pre-commit autoupdate +# Run all: pre-commit run --all-files + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-added-large-files + args: ["--maxkb=5000"] + - id: check-merge-conflict + - id: check-yaml + - id: check-json + exclude: ^\.vscode/ + + - repo: https://github.com/DavidAnson/markdownlint-cli2 + rev: v0.17.2 + hooks: + - id: markdownlint-cli2 + + - repo: https://github.com/compilerla/conventional-pre-commit + rev: v3.6.0 + hooks: + - id: conventional-pre-commit + stages: [commit-msg] + args: + - --strict + - feat + - fix + - docs + - refactor + - test + - chore + - style + - ci + - build + - perf diff --git a/00_meta/WORKFLOW.md b/00_meta/WORKFLOW.md index 19fa6d1..a93ef78 100644 --- a/00_meta/WORKFLOW.md +++ b/00_meta/WORKFLOW.md @@ -68,14 +68,17 @@ last_updated: 2026-04-24 ## Commit / PR 규칙 +- **모든 변경은 feature 브랜치 → Pull Request 를 통해 머지**. `main` 직접 커밋 금지. - 커밋 메시지는 [Conventional Commits](https://www.conventionalcommits.org/) — `type(scope): subject` 형식, **영문**. - 예: `docs(product): add vision v0.1`, `docs(arch): propose embedding model RFC` -- PR 제목도 같은 형식. 본문에 **무엇을·왜** 변경했는지 기록. -- 자세한 형식·Type·Scope 표는 [CONTRIBUTING](../CONTRIBUTING.md#커밋-메시지-규칙) 참고. +- PR 제목도 같은 형식 (CI 에서 검증). 본문에 **무엇을·왜** 변경했는지 기록. +- [CodeRabbit](https://coderabbit.ai/) 이 PR 을 자동 리뷰. Squash merge 권장. +- 자세한 형식·Type·Scope 표·개발 세팅은 [CONTRIBUTING](../CONTRIBUTING.md) 참고. - PR 체크리스트: - [ ] frontmatter 업데이트 (`last_updated`, 필요 시 `status`/`version`) - [ ] 링크 깨짐 확인 - [ ] 관련 ADR·RFC 교차 참조 + - [ ] `pre-commit run --all-files` 통과 ## ADR (Architecture Decision Record) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0216cc..680420e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,15 +15,47 @@ Synapse는 **공개 개발(open development)** 을 지향합니다. 제품 기 작은 수정(오탈자 · 링크)은 바로 PR로 보내주셔도 됩니다. +## 개발 환경 세팅 (최초 1회) + +로컬에서 lint 를 자동 검증하려면 pre-commit 을 설치하세요. + +```bash +# pipx 권장 — 없으면 pip 로 대체 가능 +pipx install pre-commit + +# hook 등록 (commit-msg 훅 포함) +pre-commit install +pre-commit install --hook-type commit-msg + +# 한 번 전체 실행해 보기 +pre-commit run --all-files +``` + +실행되는 검사: + +- **markdownlint-cli2** — 마크다운 스타일 (`.markdownlint.yaml`) +- **conventional-pre-commit** — 커밋 메시지 Conventional Commits 검증 +- 공통 위생(trailing whitespace · EOF · YAML 구문 · 대용량 파일 방지) + +CI (`.github/workflows/ci.yml`) 에서도 동일한 검사가 PR·main push 마다 실행됩니다. + ## Pull Request 가이드 -1. **브랜치**를 만들어 작업합니다. 브랜치 이름은 `type/topic` 권장 (예: `docs/vision-v2`, `feat/agent-graph`). -2. 커밋 메시지는 [Conventional Commits](https://www.conventionalcommits.org/) 를 따르며 **영문**으로 작성합니다. 자세한 규칙은 아래 "커밋 메시지 규칙" 섹션. -3. PR을 열 때 아래 체크리스트를 확인해 주세요. - - [ ] 변경한 문서의 `frontmatter` (`last_updated`, 필요 시 `status`·`version`)를 업데이트했나요? - - [ ] 관련 ADR·RFC가 있다면 상호 참조 링크를 추가했나요? - - [ ] 링크 깨짐·마크다운 렌더 오류가 없는지 로컬에서 확인했나요? - - [ ] 개인 식별 정보(PII) 또는 민감 데이터가 포함되지 않았나요? +**모든 변경은 feature 브랜치를 통해 Pull Request 로 머지합니다.** `main` 에 직접 커밋하지 마세요. + +1. **브랜치 생성**: 이름은 `type/topic` 권장. 예: `docs/vision-v2`, `feat/agent-graph`, `fix/broken-link`. +2. **커밋**: [Conventional Commits](https://www.conventionalcommits.org/) **영문** 형식. 자세한 규칙은 아래 "커밋 메시지 규칙". +3. **PR 오픈**: 제목도 같은 형식 (CI 에서 자동 검증). 본문 체크리스트를 채워 주세요. +4. **자동 리뷰**: [CodeRabbit](https://coderabbit.ai/) 이 PR 오픈·업데이트 시 자동으로 코멘트를 남깁니다. 크리티컬 이슈는 해결한 뒤 재요청하세요. +5. **머지**: Squash merge 권장 — PR 제목이 `main` 의 커밋 메시지가 됩니다. + +### PR 체크리스트 + +- [ ] 변경한 문서의 `frontmatter` (`last_updated`, 필요 시 `status`·`version`)를 업데이트했나요? +- [ ] 관련 ADR·RFC 가 있다면 상호 참조 링크를 추가했나요? +- [ ] 링크 깨짐·마크다운 렌더 오류가 없는지 로컬에서 확인했나요? +- [ ] 개인 식별 정보(PII) 또는 민감 데이터가 포함되지 않았나요? +- [ ] 로컬에서 `pre-commit run --all-files` 가 통과했나요? ## 커밋 메시지 규칙 diff --git a/README.md b/README.md index ce6a056..0493c93 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ Synapse는 현재 **단일 오너** 가 주도하지만, 작업 단위로 아래 - **질문 / 토론** → [`Discussion` 이슈](../../issues/new?template=discussion.md) 또는 Discussions - **오탈자 / 링크 / 사실 오류** → [`Doc Fix` 이슈](../../issues/new?template=doc_fix.md) 또는 Pull Request -커밋 메시지([Conventional Commits](https://www.conventionalcommits.org/), 영문)·PR 체크리스트 등 자세한 규칙은 [CONTRIBUTING](CONTRIBUTING.md) 을 참고해 주세요. 모든 상호작용은 [Code of Conduct](CODE_OF_CONDUCT.md) 를 따릅니다. +모든 변경은 **feature 브랜치 → PR** 을 통해 머지됩니다. PR 은 [CodeRabbit](https://coderabbit.ai/) 이 자동으로 리뷰하며, CI 가 pre-commit lint 와 PR 제목 포맷을 검증합니다. 개발 환경 세팅·커밋 메시지 규칙 등 자세한 내용은 [CONTRIBUTING](CONTRIBUTING.md) 을 참고해 주세요. 모든 상호작용은 [Code of Conduct](CODE_OF_CONDUCT.md) 를 따릅니다. ## 라이선스