git-conventions

Git の規約に関するスキル

このスキルでは、クリーンで読みやすいリポジトリの履歴を保つための、Git の規約、ワークフローのベストプラクティス、標準化されたコミット形式に関する包括的なガイダンスを提供します。

使用する場面

次のような場合に、このスキルを有効にします：

• 標準に沿ったコミットメッセージを作成する
• チームの Git ワークフローを確立する
• ブランチの命名規則を設定する
• Conventional Commits を導入する
• 変更履歴の自動生成を作成する
• Git の衛生状態についてコードレビューを行う
• チームメンバーに Git の実践方法をオンボーディングする

Conventional Commits

形式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

コミットの種類

主な種類：

• feat：ユーザー向けの新機能
• fix：ユーザー向けのバグ修正
• docs：ドキュメントのみの変更
• style：コードスタイルの変更（フォーマット、セミコロンの不足など）
• refactor：バグ修正にも機能追加にも該当しないコード変更
• perf：パフォーマンスの改善
• test：テストの追加または修正
• build：ビルドシステムまたは依存関係の変更
• ci：CI 設定ファイルおよびスクリプトの変更
• chore：src ファイルや test ファイルを変更しないその他の変更
• revert：以前のコミットの取り消し

例

シンプルなコミット：

feat: add user authentication

Implement JWT-based authentication system with refresh tokens.
Includes middleware for protected routes.

Closes #123

破壊的変更：

feat!: redesign API response format

BREAKING CHANGE: API now returns data in camelCase instead of snake_case.
Migration guide available in docs/migration-v2.md.

Refs: #456

スコープを指定する場合：

fix(auth): resolve token expiration edge case

Token validation now properly handles timezone offsets.
Adds retry logic for expired tokens within 5-minute grace period.

複数の段落がある場合：

refactor(database): optimize query performance

- Add indexes on frequently queried columns
- Implement connection pooling
- Cache common queries with Redis
- Reduce N+1 queries in user associations

Performance improved by 60% in production testing.

Reviewed-by: Jane Doe <[email protected]>
Refs: #789

コミットメッセージのルール

1. 件名行：

   • 命令形を使います（「added」や「adds」ではなく「add」）
   • 先頭の文字は大文字にしません
   • 末尾にピリオドを付けません
   • 最大 50 文字（目安）
   • 本文とは空行で区切ります

2. 本文：

   • 72 文字で折り返します
   • 方法ではなく、何を、なぜ行うのかを説明します
   • 複数の項目には箇条書きを使います
   • Issue と PR を参照します

3. フッター：

   • 破壊的変更は「BREAKING CHANGE:」で始めます
   • Issue を参照します：「Closes #123」、「Fixes #456」、「Refs #789」
   • 共著者を記載します：「Co-authored-by: Name 」

ブランチの命名規則

形式のパターン

<type>/<issue-number>-<short-description>

ブランチの種類

一般的な接頭辞：

• feature/ または feat/ - 新機能
• fix/ または bugfix/ - バグ修正
• hotfix/ - 本番環境に対する緊急修正
• release/ - リリースの準備
• docs/ - ドキュメントの更新
• refactor/ - コードのリファクタリング
• test/ - テストの追加または修正
• chore/ - メンテナンスタスク
• experimental/ または spike/ - 概念実証

例

# Feature branches
feature/123-user-authentication
feat/456-add-payment-gateway
feature/oauth-integration

# Bug fix branches
fix/789-resolve-memory-leak
bugfix/login-redirect-loop
fix/456-null-pointer-exception

# Hotfix branches
hotfix/critical-security-patch
hotfix/production-database-issue

# Release branches
release/v1.2.0
release/2024-Q1

# Documentation branches
docs/api-reference-update
docs/123-add-contributing-guide

# Refactor branches
refactor/database-layer
refactor/456-simplify-auth-flow

# Experimental branches
experimental/graphql-api
spike/performance-optimization

ブランチの命名規則

1. 単語の区切りにはハイフンを使います（アンダースコアは使いません）
2. 小文字のみを使います（大文字は避けます）
3. 短く、かつ内容がわかる名前にします（最大 50 文字）
4. 該当する場合はIssue 番号を含めます
5. ハイフンとスラッシュ以外の特殊文字は避けます
6. 末尾にスラッシュを付けません
7. チーム内で一貫性を保ちます

保護ブランチ戦略

メインブランチ

main/master：

• 本番環境に対応できるコード
• 常にデプロイ可能
• 必須レビューで保護
• 直接コミットは禁止
• release ブランチまたは hotfix ブランチからのみマージ

develop：

• 機能を統合するブランチ
• 本番前のテスト
• CI チェックで保護
• 機能ブランチのマージ先

staging：

• 本番前の環境
• QA テスト用ブランチ
• 新機能を含む本番環境のミラー

保護ルール

# Example GitHub branch protection
main:
  require_pull_request_reviews:
    required_approving_review_count: 2
    dismiss_stale_reviews: true
    require_code_owner_reviews: true

  require_status_checks:
    strict: true
    contexts:
      - continuous-integration
      - code-quality
      - security-scan

  enforce_admins: true
  require_linear_history: true
  allow_force_pushes: false
  allow_deletions: false

セマンティックバージョニング

バージョン形式

MAJOR.MINOR.PATCH[-prerelease][+build]

例：

• 1.0.0 - 初回リリース
• 1.2.3 - パッチを含むマイナーアップデート
• 2.0.0-alpha.1 - プレリリースのアルファ版
• 1.5.0-rc.2+20240321 - ビルドメタデータを含むリリース候補

バージョンの増分ルール

MAJOR（X.0.0）：

• 破壊的変更
• API の互換性が失われる変更
• 大幅な再設計
• 非推奨機能の削除

MINOR（x.Y.0）：

• 新機能（後方互換性あり）
• 非推奨機能（引き続き動作）
• 大幅な内部変更

PATCH（x.y.Z）：

• バグ修正
• セキュリティパッチ
• パフォーマンスの改善
• ドキュメントの更新

バージョン用の Git タグ

# Create annotated tag
git tag -a v1.2.3 -m "Release version 1.2.3

- Add user authentication
- Fix memory leak in cache
- Improve API performance"

# Push tags to remote
git push origin v1.2.3

# Push all tags
git push --tags

# Create pre-release tag
git tag -a v2.0.0-beta.1 -m "Beta release for v2.0.0"

# Delete tag
git tag -d v1.2.3
git push origin :refs/tags/v1.2.3

ワークフローパターン

Git Flow

ブランチ構成：

• main - 本番リリース
• develop - 次回リリースの開発
• feature/* - 新機能
• release/* - リリースの準備
• hotfix/* - 緊急修正

機能開発のワークフロー：

# Start feature
git checkout develop
git pull origin develop
git checkout -b feature/123-new-feature

# Work on feature
git add .
git commit -m "feat: implement user authentication"

# Finish feature
git checkout develop
git pull origin develop
git merge --no-ff feature/123-new-feature
git push origin develop
git branch -d feature/123-new-feature

リリースのワークフロー：

# Start release
git checkout develop
git checkout -b release/v1.2.0

# Prepare release (bump version, update changelog)
git commit -m "chore: prepare release v1.2.0"

# Merge to main
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"

# Merge back to develop
git checkout develop
git merge --no-ff release/v1.2.0

# Cleanup
git branch -d release/v1.2.0

ホットフィックスのワークフロー：

# Start hotfix from main
git checkout main
git checkout -b hotfix/critical-bug

# Fix and commit
git commit -m "fix: resolve critical security vulnerability"

# Merge to main
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v1.2.1 -m "Hotfix v1.2.1"

# Merge to develop
git checkout develop
git merge --no-ff hotfix/critical-bug

# Cleanup
git branch -d hotfix/critical-bug

GitHub Flow

簡略化されたワークフロー：

• main - 常にデプロイ可能
• feature/* - すべての変更を機能ブランチで行う

ワークフロー：

# Create feature branch
git checkout -b feature/add-logging
git push -u origin feature/add-logging

# Make changes and commit
git commit -m "feat: add structured logging"
git push origin feature/add-logging

# Open pull request on GitHub
# After review and CI passes, merge to main
# Deploy from main

トランクベース開発

単一の main ブランチ：

• 寿命の短い機能ブランチ（2 日未満）
• main への頻繁な統合
• 未完成の機能にはフィーチャーフラグを使用
• 継続的インテグレーション

ワークフロー：

# Create short-lived branch
git checkout -b update-api-docs
git push -u origin update-api-docs

# Make small, incremental changes
git commit -m "docs: update API endpoint documentation"
git push origin update-api-docs

# Immediately create PR and merge (same day)
# Main branch always deployable with feature flags

プルリクエストの規約

PR タイトルの形式

Conventional Commits 形式を使用します：

feat(auth): add OAuth2 provider support
fix(api): resolve rate limiting edge case
docs: update installation guide

PR の説明テンプレート

## Summary
Brief description of changes and motivation.

## Changes
- Bullet list of specific changes
- Reference architecture decisions
- Note any breaking changes

## Testing
- Unit tests added/updated
- Integration tests passed
- Manual testing performed

## Screenshots (if applicable)
[Add screenshots for UI changes]

## Related Issues
Closes #123
Refs #456

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Changelog updated
- [ ] Breaking changes documented
- [ ] Code reviewed by team

レビューのガイドライン

レビュー担当者のチェックリスト：

• コードがスタイルガイドに従っている
• コミットメッセージが規約に従っている
• テストが十分に網羅されている
• ドキュメントが更新されている
• セキュリティ上の脆弱性がない
• パフォーマンスに関する考慮事項に対応している
• 破壊的変更に正当な理由がある

変更履歴の管理

Keep a Changelog 形式

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- User authentication with JWT tokens
- API rate limiting middleware

### Changed
- Updated database schema for better performance

### Deprecated
- Old authentication endpoint (use /api/v2/auth instead)

### Removed
- Legacy XML API support

### Fixed
- Memory leak in cache implementation
- Race condition in concurrent requests

### Security
- Patch for SQL injection vulnerability

## [1.2.0] - 2024-03-15

### Added
- Real-time notifications system
- User profile customization

### Fixed
- Login redirect loop issue
- Session timeout handling

## [1.1.0] - 2024-02-01

### Added
- Search functionality
- Export to CSV feature

### Changed
- Improved UI responsiveness

変更履歴の自動生成

次のようなツールを使用します：

• conventional-changelog - コミットから変更履歴を生成
• release-please - リリースと変更履歴を自動化
• semantic-release - バージョン管理を完全に自動化

ベストプラクティス

1. こまめにコミットする： 小さく、焦点を絞ったコミットはレビューや取り消しが容易です
2. 明確なメッセージを書く： 未来のあなたは、今のあなたに感謝するでしょう
3. 1 つのコミットにつき 1 つの目的： 各コミットでは、1 つの論理的な変更に対応します
4. コミット前にテストする： コミットする前にコードが動作することを確認します
5. イシューを参照する： コミットをイシュートラッカーにリンクします
6. 自分の変更をレビューする： コミット前に git diff --staged を使用します
7. 履歴を整理する： 直線的な履歴を保つため、機能ブランチをリベースします
8. コミットに署名する： 検証済みコミットには GPG 署名を使用します
9. .gitignore を適切に使用する： 機密ファイルや生成ファイルは決してコミットしません
10. 規約を文書化する： チームの規約をリポジトリのドキュメントに記載します

チームのワークフロー例

小規模チーム（開発者 2～5 人）

# Simplified workflow
- Direct commits to main (with PR reviews)
- Feature branches for major changes
- Tags for releases
- Linear history preferred

中規模チーム（開発者 5～20 人）

# Git Flow variant
- Protected main and develop branches
- Feature branches required
- Release branches for versions
- Hotfix workflow for emergencies
- Squash merge for clean history

大規模チーム（開発者 20 人以上）

# Trunk-based with feature flags
- Protected main branch
- Very short-lived feature branches
- Feature flags for incomplete work
- Automated testing and deployment
- Multiple daily integrations

リソース

追加のガイドやテンプレートは assets/ ディレクトリにあります：

• templates/ - コミットメッセージと PR のテンプレート
• examples/ - 実際のワークフロー例
• tools/ - Git フックと自動化スクリプト

references/ ディレクトリには、次の資料があります：

• Conventional Commits の仕様
• セマンティックバージョニングのドキュメント
• Git Flow と GitHub Flow のガイド
• Keep a Changelog の規約