git-hygiene-enforcer

Git の健全性を保つためのルール

チーム全体で、一貫性のある高品質な Git の運用を徹底します。

基本的なワークフロー

1. 規約を決める：コミット形式（Conventional Commits、Angular など）を選択します
2. コミットフックを設定する：git hooks とともに commitlint をインストールします
3. ブランチルールを設定する：命名パターンと保護ルールを定義します
4. PR テンプレートを作成する：プルリクエストの説明を標準化します
5. ワークフローを追加する：自動チェック用に GitHub Actions または GitLab CI を設定します
6. プロセスを文書化する：Git のガイドラインをまとめた CONTRIBUTING.md を作成します
7. バイパス手段を用意する：緊急時のオーバーライド手順を文書化します

Conventional Commits

形式：<type>(<scope>): <description>

タイプ：

• feat：新機能
• fix：バグ修正
• docs：ドキュメントの変更
• style：コードスタイルの変更（フォーマットなど）
• refactor：コードのリファクタリング
• test：テストの追加または変更
• chore：ビルド／ツールの変更
• perf：パフォーマンスの改善
• ci：CI/CD の変更

例：

feat(auth): add OAuth2 login
fix(api): resolve race condition in user endpoint
docs(readme): update installation instructions
refactor(utils): simplify date formatting logic

コミットフックの設定

Husky + Commitlint を使用する場合

1. 依存関係をインストールします：

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
npx husky init

2. commitlint を設定します（commitlint.config.js）：

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "test",
        "chore",
        "perf",
        "ci",
      ],
    ],
    "subject-case": [2, "never", ["upper-case"]],
    "subject-empty": [2, "never"],
    "subject-full-stop": [2, "never", "."],
    "header-max-length": [2, "always", 100],
  },
};

3. commit-msg フックを追加します（.husky/commit-msg）：

#!/bin/sh
npx --no -- commitlint --edit $1

pre-commit を使用する場合（Python）

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.0.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

ブランチ命名規約

パターン： <type>/<ticket-id>-<description>

例：

feature/AUTH-123-oauth-login
bugfix/API-456-user-race-condition
hotfix/PROD-789-payment-error
refactor/DB-321-optimize-queries

ブランチ保護ルール：

• PR レビューを必須にする（レビュアー 1～2 名）
• ステータスチェックの合格を必須にする
• ブランチが最新の状態であることを必須にする
• 線形な履歴を徹底する（マージコミットなし）
• 署名付きコミットを必須にする（任意）

プルリクエストテンプレート

.github/pull_request_template.md

## Description



## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Related Issue

Closes #

## How Has This Been Tested?



- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing

## Checklist

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published

## Screenshots (if applicable)

代替案：シンプルなテンプレート

## What



## Why



## How



## Testing

GitHub Actions ワークフロー

.github/workflows/pr-checks.yml

name: PR Checks

on:
  pull_request:
    branches: [main, develop]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Validate PR title
        uses: amannn/action-semantic-pull-request@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Check branch naming
        run: |
          BRANCH="${{ github.head_ref }}"
          if [[ ! $BRANCH =~ ^(feature|bugfix|hotfix|refactor|docs|chore)/.+ ]]; then
            echo "Branch name doesn't follow convention: <type>/<description>"
            exit 1
          fi

      - name: Lint commits
        uses: wagoid/commitlint-github-action@v5

      - name: Check for merge commits
        run: |
          if git log --merges origin/${{ github.base_ref }}..HEAD | grep -q 'Merge'; then
            echo "Merge commits detected. Please rebase your branch."
            exit 1
          fi

Git の設定

.gitattributes

# Auto detect text files and perform LF normalization
* text=auto

# Explicitly mark files as text
*.js text
*.ts text
*.json text
*.md text
*.yml text

# Binary files
*.png binary
*.jpg binary
*.gif binary
*.ico binary
*.woff binary
*.woff2 binary

.gitignore のベストプラクティス

# Dependencies
node_modules/
vendor/

# Environment
.env
.env.local

# Build outputs
dist/
build/
*.log

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

コードレビューのガイドライン

CONTRIBUTING.md のセクション

## Pull Request Process

1. **Create a branch** following naming convention: `type/description`
2. **Make commits** using conventional commit format
3. **Write tests** for new features or bug fixes
4. **Update documentation** if APIs change
5. **Ensure CI passes** before requesting review
6. **Request review** from 1-2 team members
7. **Address feedback** and update PR
8. **Squash and merge** when approved

## Code Review Checklist

**Reviewers should verify:**

- [ ] Code is clear and understandable
- [ ] Tests cover new/changed code
- [ ] No obvious bugs or security issues
- [ ] Follows project conventions
- [ ] Documentation is updated
- [ ] No unnecessary changes included

**Constructive feedback:**

- Be specific and actionable
- Assume good intent
- Ask questions instead of making demands
- Praise good solutions

コミットメッセージの検証

commit-msg フックの例

#!/bin/bash
# .husky/commit-msg

commit_msg=$(cat "$1")

# Check conventional commit format
if ! echo "$commit_msg" | grep -qE '^(feat|fix|docs|style|refactor|test|chore|perf|ci)(\(.+\))?: .+'; then
  echo "Error: Commit message doesn't follow Conventional Commits format"
  echo "Format: <type>(<scope>): <description>"
  echo "Example: feat(auth): add OAuth2 login"
  exit 1
fi

# Check message length
if [ ${#commit_msg} -gt 100 ]; then
  echo "Error: Commit message too long (max 100 characters)"
  exit 1
fi

緊急時のバイパス手順

フックをスキップする（必要最小限にとどめてください）

# Skip commit message validation
git commit --no-verify -m "hotfix: critical production fix"

# Force push (use with caution)
git push --force-with-lease

# Override PR checks (requires admin)
# Use GitHub UI: "Merge without waiting for checks"

バイパスが許容される場合

• 本番環境のホットフィックス：ユーザーに影響する重大なバグ
• リバート：問題のある変更をロールバックする場合
• 緊急時：インフラストラクチャの障害

バイパス手順の文書化

CONTRIBUTING.md に以下を記載します：

## Emergency Procedures

In rare cases, you may need to bypass git hooks:

1. **Commit without hooks**: `git commit --no-verify`

   - Only for production hotfixes
   - Fix commit message in follow-up PR

2. **Force push**: `git push --force-with-lease`
   - After approved history rewrite
   - Coordinate with team first

Always create a follow-up PR to fix any bypassed checks.

推奨ワークフロー

## Development Workflow

1. **Start work**
   ```bash
   git checkout main
   git pull
   git checkout -b feature/TICKET-123-new-feature
   ```

2. 変更を加える

   # Make your changes
   git add .
   git commit -m "feat(api): add user search endpoint"
   

3. 最新の状態を保つ

   git fetch origin
   git rebase origin/main
   

4. プッシュして PR を作成する

   git push origin feature/TICKET-123-new-feature
   # Create PR via GitHub/GitLab
   

5. フィードバックに対応する

   # Make changes
   git add .
   git commit -m "fix: address review feedback"
   git push
   

6. マージする

   • UI からスカッシュマージする
   • マージ後にブランチを削除する

## Installation Checklist

- [ ] Commitlint config (commitlint.config.js)
- [ ] Git hooks (.husky/ or .git/hooks/)
- [ ] PR template (.github/pull_request_template.md)
- [ ] Branch protection rules (via GitHub settings)
- [ ] CI workflow for PR validation
- [ ] CONTRIBUTING.md with git guidelines
- [ ] .gitattributes for consistent line endings
- [ ] Emergency bypass documentation

## Best Practices

1. **Keep commits atomic**: One logical change per commit
2. **Write descriptive messages**: Explain why, not just what
3. **Reference tickets**: Include issue/ticket IDs
4. **Rebase before merging**: Keep history clean
5. **Review your own PR first**: Self-review catches many issues
6. **Respond to feedback promptly**: Don't leave PRs hanging
7. **Delete merged branches**: Keep repository tidy
8. **Use draft PRs**: For work-in-progress changes