GitHub 使用規範完全ガイド: 提出から協力までのベストプラクティス

前言#

もしあなたがチームと一緒に GitHub を使ってコードを管理しているか、オープンソースプロジェクトに貢献しているなら、次のような混乱に直面したことがあるでしょう：コミットメッセージはどう書くべきか？ブランチはどう管理するか？プルリクエストはどのようなルールに従うべきか？これらは一見単純な問題のように思えますが、実際にはプロジェクトのメンテナンス性やチームの協力効率に直接影響を与えます。

開発チームは、規範的なワークフローを通じてコードバージョンを管理する必要があります。本記事では、GitHub の使用規範を体系的に紹介します。これには、コミットの提出規範、ブランチ管理戦略、プルリクエストのプロセス、およびプロジェクト文書の規範が含まれます。GitHub に初めて触れる初心者から、チームの協力プロセスを最適化したい開発者まで、実用的なアドバイスを見つけることができるでしょう。

この記事を読み終えると、あなたは以下を習得します:

明確で規範的なコミットメッセージを書く方法
チームに適したブランチ管理戦略を選択する方法
プルリクエストを正しく開始し、レビューする方法
規範的なオープンソースプロジェクト構造を構築する方法

コミットメッセージ提出規範#

なぜ規範的なコミットメッセージが必要なのか#

コミットメッセージを読むことで、コードを読むことなく、バージョンの変更内容を大まかに理解できます。規範的なコミットメッセージは、チームメンバーがコードの変更を理解するのに役立つだけでなく、以下のことも可能にします:

プロジェクトの履歴を迅速に閲覧し、機能の進化を理解する
CHANGELOG ドキュメントを自動生成する
バグの発生源や機能の実装を追跡しやすくする
コードレビューの効率を向上させる

Angular 規範#

Angular コミット規範は、最初に広く採用された規範のセットであり、その後、より一般的な Conventional Commits に進化しました。現在、一般的に言われる「業界標準」は、後者に偏っています。

<type>(<scope>): <subject>

<body>

<footer>

構造説明:

ヘッダー（必須）: type、scope（オプション）、subject を含む
ボディ（オプション）: 今回のコミットの詳細な説明
フッター（オプション）: 関連する Issue または非互換の変更を説明

ヘッダー部分詳細#

Type（タイプ） - 必須

今回のコミットの種類を示すために使用され、一般的なタイプには以下が含まれます:

feat: 新機能の追加（feature）
fix: バグの修正
docs: ドキュメントの変更（documentation）
style: コードフォーマットの調整（コードの実行に影響しない）
refactor: リファクタリング（新機能の追加でもバグの修正でもない）
perf: パフォーマンスの最適化
test: テストの追加
chore: ビルドプロセスや補助ツールの変更
ci: CI 設定ファイルやスクリプトの変更
build: ビルドシステムや外部依存関係に影響を与える変更
revert: 以前にコミットされた変更を元に戻す

Scope（範囲） - オプション

コミットが影響を与える範囲を示すために使用されます。例えば、データ層、制御層、ビュー層など、プロジェクトによって異なります。例: Controller、Service、API、UI、Database など。

Subject（テーマ） - 必須

コミットの簡潔な説明で、一般的に 50 文字を超えないようにします。書き方の要件:

命令形、現在形を使用: "change" とし、"changed" や "changes" は使用しない
最初の文字は小文字
終わりに句点を付けない

ボディ部分#

ボディは今回のコミットの詳細な説明を行い、以下を示します:

なぜこの変更が必要なのか
変更の影響範囲
以前の動作との比較

1 行は 72 文字を超えないようにします。

フッター部分#

フッターは主に 2 つの状況で使用されます:

1. Issue を閉じる

キーワードを使用することで、Issue を自動的に閉じることができます:

Closes #123 - 単一の Issue を閉じる
Closes #123, #456 - 複数の Issue を閉じる
その他のキーワード: Fixes、Resolves、Close、Fix、Resolve

2. 非互換の変更

現在のコードが前のバージョンと互換性がない場合、フッターは BREAKING CHANGE: で始まり、変更の説明、理由、移行方法を示す必要があります。

実際の例#

簡単な例:

feat(user): ユーザーログイン機能を追加

fix(api): 支払いモジュールのタイムアウト問題を解決

docs(readme): インストールガイドを更新

完全な例:

feat(shopping-cart): 商品数量セレクターを追加

カートページでユーザーが商品数量を直接変更できるようにします。
これにより、必要なクリック数が減り、ユーザーエクスペリエンスが向上します。

Closes #234

非互換の変更を含む:

refactor(api): 認証方法を変更

BREAKING CHANGE: 認証 API は API キーの代わりに OAuth 2.0 を要求します。
すべての既存の統合は、新しい OAuth フローを使用するように更新する必要があります。
移行ガイドを参照: docs/migration-oauth.md

規範を保証するためのツールの使用#

Commitizen - インタラクティブなコミットツール

Commitizen は、規範的なコミットメッセージを生成するのを助けるフレンドリーなインターフェースを提供します。

インストールと設定:

# Commitizen をインストール
npm install --save-dev commitizen

# Angular 規範アダプターをインストール
npm install --save-dev cz-conventional-changelog

# 初期化
npx commitizen init cz-conventional-changelog --save-dev --save-exact

使用方法:

# git commit の代わりに git cz を使用
git add .
git cz

Commitlint - コミットメッセージ検証ツール

指定された規範に従わないコミットメッセージを lint するのに役立ち、違反があればコミットを拒否します。

インストールと設定:

# インストール
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# 設定ファイルを作成
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

Husky と組み合わせて使用:

# インストール
npm install husky --save-dev
npx husky init

# commit-msg フックを追加
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

これにより、毎回のコミット時に規範に従わない場合は拒否されます。

ブランチ管理戦略#

なぜブランチ管理戦略が必要なのか#

注意を払わないと、枝葉が生い茂り、あちこちに開放されたバージョンリポジトリが残る可能性が高く、どこにでもブランチがあり、メインの発展の脈絡が全く見えなくなります。合理的なブランチ戦略は以下を可能にします:

異なる機能の開発を隔離し、相互干渉を避ける
並行開発と迅速な反復をサポートする
メインブランチのコードの安定性を保証する
バージョンのリリースとロールバックを容易にする

Git Flow - クラシックなブランチ管理モデル#

Git Flow は、最初に体系的に提案され、影響力のあるワークフローの一つであり、明確なリリースサイクルのあるプロジェクトに適しています。

主要ブランチ

1. main ブランチ

常に安定したリリース可能な状態を維持
他のブランチをマージすることでのみ更新
各マージにはバージョンタグを付ける必要があります

2. develop ブランチ

日常開発のメインブランチ
次回のリリースの最新の開発成果を含む
コードが安定した状態に達したら、main にマージしてリリース

補助ブランチ

1. Feature ブランチ（機能ブランチ）

Feature ブランチはモジュール機能の開発に使用され、feature-xxx という名前を付けることをお勧めします。

develop ブランチから作成
開発が完了したら、develop にマージ
命名規則: feature/機能名 または feature-機能名
開発が完了したら削除

# 機能ブランチを作成
git checkout -b feature/user-profile develop

# 開発が完了したらマージ
git checkout develop
git merge --no-ff feature/user-profile
git branch -d feature/user-profile
git push origin develop

2. Release ブランチ（プレリリースブランチ）

Release ブランチはバージョンリリースのプレリリースブランチに使用され、release-xxx という名前を付けることをお勧めします。

develop ブランチから作成
リリース前のテストと小さなバグ修正に使用
テストが通過したら、main と develop にマージ
命名規則: release/バージョン番号 または release-バージョン番号

# プレリリースブランチを作成
git checkout -b release/1.2.0 develop

# バージョン番号などの準備作業を行う
# テストとバグ修正を行う

# main にマージ
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "リリースバージョン 1.2.0"

# develop にマージ
git checkout develop
git merge --no-ff release/1.2.0

# ブランチを削除
git branch -d release/1.2.0

3. Hotfix ブランチ（ホットフィックスブランチ）

Hotfix ブランチはオンラインの緊急バグ修正のためのブランチで、hotfix-xxx という名前を付けることをお勧めします。

main ブランチから作成
修正が完了したら、main と develop にマージ
main にマージする際に修正バージョンタグを付ける
命名規則: hotfix/問題の説明 または hotfix-問題の説明

# ホットフィックスブランチを作成
git checkout -b hotfix/critical-bug main

# バグを修正
# ...

# main にマージ
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v1.2.1 -m "クリティカルバグのホットフィックス"

# develop にマージ
git checkout develop
git merge --no-ff hotfix/critical-bug

# ブランチを削除
git branch -d hotfix/critical-bug

GitHub Flow - 簡略化されたワークフロー#

GitHub Flow の利点は、Git Flow よりも簡単で、CI/CD（継続的インテグレーション / 継続的デプロイ）プロセスのプロジェクトに適しています。

基本原則:

main ブランチは常にデプロイ可能である
新機能を開発する際は、main から説明的なブランチを作成
定期的にローカルブランチにコミットし、同名のリモートブランチにプッシュ
助けが必要な場合やマージの準備ができた場合は、プルリクエストを発行
レビューとテストを経て、main にマージ
マージ後は即座にデプロイ

ワークフロー:

# 1. 機能ブランチを作成
git checkout -b add-user-avatar main

# 2. 開発を行い、コミット
git add .
git commit -m "feat: ユーザーアバターのアップロードを追加"

# 3. リモートにプッシュ
git push origin add-user-avatar

# 4. GitHub 上でプルリクエストを発行

# 5. コードレビューが通過したら、GitHub 上で main にマージ

# 6. マージ後は即座にデプロイ

GitLab Flow - 環境指向のワークフロー#

GitLab Flow は GitHub Flow にステージング、プロダクションなどのブランチを追加したものです。これは Git Flow と GitHub Flow の利点を組み合わせ、継続的インテグレーションと継続的デプロイにより重点を置いています。

核心思想:

機能ブランチを使用して開発
コードレビューを経て main にマージ
main を開発のメインブランチとして使用
異なる環境に対応するブランチを作成: staging、production
コードは環境に応じて進める: main → staging → production

適用シーン:

複数の環境にデプロイする必要があるプロジェクト
継続的インテグレーションと継続的デプロイを強調する
異なる環境でコードを検証する必要があるプロジェクト

どのブランチ戦略を選択するか#

Git Flow を選択する場合:

プロジェクトに明確なバージョンリリースサイクルがある
複数のバージョンを同時に維持する必要がある
チーム規模が大きく、役割分担が明確である
コード品質に対する要求が厳しい

GitHub Flow を選択する場合:

プロジェクトが継続的にデプロイされる必要がある
チーム規模が小さく、コミュニケーションがスムーズである
シンプルなワークフローを維持したい
複数の生産バージョンを維持する必要がない

GitLab Flow を選択する場合:

複数の環境でコードを検証する必要がある
CI/CD プロセスを強調する
環境の隔離と段階的な進行が必要である

プルリクエストのベストプラクティス#

プルリクエストとは何か#

プルリクエストは通知メカニズムです。他の人のコードを修正し、あなたの修正を元の著者に通知し、あなたの修正をマージしてほしいというのがプルリクエストです。

PR の基本原則#

1 つの PR は 1 つの事柄に集中し、過度に大きな PR を避けるべきです。具体的には:

1. 単一責任

1 つの PR は 1 つの問題を解決するか、1 つの機能を実現する
複数の無関係な変更を同じ PR に混ぜない
複数の機能が必要な場合は、複数の PR に分けて提出する

2. PR のサイズを制御する

変更するファイルは 12 個未満が望ましい（ビルド生成ファイルを除く）
コード行数は合理的な範囲に制御する（推奨は 400 行未満）
大きすぎる PR はレビューが難しく、問題を引き起こしやすい

3. 明確な説明

PR のタイトルと説明は明確であるべきです:

タイトル形式: [タイプ] + 動詞 + 名詞 + [形容詞] + [名詞]
例えば: Collapse コンポーネントが展開できない問題を修正、ユーザーアバターのアップロード機能を追加

プルリクエストを発行する方法#

標準プロセス:

ターゲットリポジトリをフォーク（外部プロジェクトの場合）
ローカルにクローン

git clone https://github.com/あなたのユーザー名/プロジェクト名.git
cd プロジェクト名

機能ブランチを作成

git checkout -b feature/my-feature

開発を行い、コミット

git add .
git commit -m "feat: 新機能を追加"

リモートにプッシュ

git push origin feature/my-feature

GitHub 上でプルリクエストを作成
- あなたのフォークリポジトリに移動
- "Compare & pull request" をクリック
- 正しい base ブランチ（通常は develop または main）を選択
- PR のタイトルと説明を記入
- プルリクエストを提出

PR 説明テンプレート#

良い PR 説明には以下の内容が含まれるべきです:

## 改動説明
本 PR の目的と変更内容を簡潔に説明します。

## 改動タイプ
- [ ] バグ修正
- [ ] 新機能
- [ ] コードリファクタリング
- [ ] ドキュメント更新
- [ ] パフォーマンス最適化
- [ ] その他（説明してください）:

## 関連 Issue
Closes #123
Relates #456

## テスト説明
- テストケースは追加/更新済み
- ローカルテストは通過
- すべての CI チェックは通過

## スクリーンショット/録画
（UI の変更がある場合は、スクリーンショットまたは録画を提供してください）

## 追加説明
（レビューアに注意してほしいその他の事項）

コードレビューの要点#

PR 提出者として:

提出前に自分でコードをレビューする
コードがプロジェクトのコーディング規範に従っていることを確認する
すべてのテストが通過していることを確認する
レビューの意見に迅速に応答する
PR 内でレビュー時に発見された無関係な問題を修正しない

コードレビュー者として:

コードのロジックと設計が合理的かどうかに注目する
潜在的なバグやセキュリティ問題がないか確認する
コードがチームの規範に従っていることを確認する
建設的なフィードバックを提供する
迅速に応答し、PR が長時間放置されないようにする

よくある問題の対処#

1. PR とメインブランチの衝突

# メインブランチを更新
git checkout main
git pull origin main

# 機能ブランチに戻り、rebase
git checkout feature/my-feature
git rebase main

# 衝突を解決した後、続行
git add .
git rebase --continue

# 強制プッシュ（コミット履歴が変更されたため）
git push origin feature/my-feature --force

2. 既に提出した PR を修正する必要がある

元のブランチで引き続きコミットすれば、GitHub が自動的に PR を更新します:

git add .
git commit -m "fix: レビューコメントに対処"
git push origin feature/my-feature

3. PR がマージされた後のクリーンアップ

# ローカルブランチを削除
git branch -d feature/my-feature

# リモートブランチを削除
git push origin --delete feature/my-feature

# ローカルメインブランチを更新
git checkout main
git pull origin main

GitHub プロジェクト規範#

必須ファイル#

規範的な GitHub プロジェクトには、以下のファイルが含まれるべきです:

1. README.md

これはプロジェクトの顔です。README ファイルは、プロジェクトの目的と機能を簡潔に説明するだけでなく、インストールガイド、使用方法、貢献ガイド、ライセンス情報を含むべきです。

基本構造:

# プロジェクト名

簡潔なプロジェクトの説明

## 機能特性
- 特性 1
- 特性 2

## クイックスタート

### 環境要件
- Node.js >= 14
- npm >= 6

### インストール
npm install

### 使用方法

npm start

## ドキュメント

詳細なドキュメントは [ドキュメントディレクトリ](./docs) を参照してください。

## 貢献ガイド

[CONTRIBUTING.md](./CONTRIBUTING.md) を参照してください。

## ライセンス

[MIT](./LICENSE)

2. .gitignore

各リポジトリには、事前定義されたファイルやディレクトリを無視するために .gitignore ファイルを使用する必要があります。

あなたの技術スタックに合わせた .gitignore ファイルを生成するには、gitignore.io を使用することをお勧めします。

3. LICENSE

適切なオープンソースライセンスを選択します:

MIT - 最も緩やかで、商業利用を許可
Apache 2.0 - 特許保護を提供
GPL - 派生作品もオープンソースにすることを要求
BSD - MIT に似ていますが、いくつかの制限があります

4. CONTRIBUTING.md

プロジェクトへの貢献方法を説明します:

Issue の提出方法
プルリクエストの提出方法
コード規範の要件
開発環境の構築
テスト要件

5. CHANGELOG.md

プロジェクトのバージョン変更履歴を記録します:

# Changelog

## [1.2.0] - 2024-12-06

### Added
- ユーザーアバターのアップロード機能を追加

### Fixed
- ログインページのスタイル問題を修正

### Changed
- データベースクエリのパフォーマンスを最適化

## [1.1.0] - 2024-11-15
...

その他のベストプラクティス#

1. メインブランチを保護する

メインブランチの内容は常にデプロイ可能であるべきで、デフォルトブランチに直接コードをコミットすべきではありません。

GitHub リポジトリの設定で:

Settings → Branches → Branch protection rules
ルールを追加して main ブランチを保護
PR レビュー後にのみマージを要求
CI チェックの通過を要求
強制プッシュを禁止

2. Issue テンプレートを使用する

.github/ISSUE_TEMPLATE ディレクトリを作成し、異なるタイプの Issue テンプレートを追加します:

bug_report.md - バグ報告テンプレート
feature_request.md - 機能リクエストテンプレート

3. Code Owners を設定する

codeowners 機能を使用して、どのチームや個人がリポジトリのレビュアーとして自動的に選ばれるかを定義できます。

.github/CODEOWNERS ファイルを作成:

# デフォルトは全員
* @team-lead

# フロントエンドコード
/src/frontend/ @frontend-team

# バックエンドコード
/src/backend/ @backend-team

# ドキュメント
/docs/ @doc-team

4. もはやメンテナンスされていないリポジトリをアーカイブする

積極的に開発されていないリポジトリに対しては、アーカイブして読み取り専用モードに設定するのがベストプラクティスです。

リポジトリの設定で「このリポジトリをアーカイブ」を選択します。

5. 機密情報のコミットを避ける

機密情報をコードにコミットしないようにしてください。安全なストレージから外部で注入された環境変数を使用できます。

環境変数や設定ファイルを使用して機密情報を管理します:

データベースパスワード
API キー
プライベートトークン
SSH キー

よくある質問と解決策#

誤ったコミットを提出した場合はどうすればよいですか？#

最近のコミットを修正:

# コミットメッセージを修正
git commit --amend -m "新しいコミットメッセージ"

# 忘れたファイルを追加
git add forgotten_file
git commit --amend --no-edit

プッシュされたコミットを取り消す:

公共ブランチでは git revert を優先し、reset --hard + --force は個人ブランチや特別な状況でのみ使用します。

# ソフトリセット（変更を保持）
git reset --soft HEAD~1
git push origin branch-name --force

# ハードリセット（変更を破棄）
# ⚠ 自分で管理している機能ブランチのみに限り、共有されている main / develop には行わないでください
git reset --hard HEAD~1
git push origin branch-name --force

複数のコミットをマージするにはどうすればよいですか？#

インタラクティブリベースを使用します:

# 最近の 3 つのコミットをマージ
git rebase -i HEAD~3

# エディタ内で、マージしたいコミットの前の pick を squash（または s）に変更
# 保存して終了した後、マージ後のコミットメッセージを編集

ブランチの衝突をどう解決するか？#

# 1. メインブランチを更新
git checkout main
git pull origin main

# 2. 機能ブランチに戻る
git checkout feature-branch

# 3. マージまたはリベース
git merge main
# または
git rebase main

# 4. 衝突を解決
# 衝突ファイルを編集し、衝突マークを削除

# 5. 解決済みとしてマーク
git add .

# 6. マージまたはリベースを続行
git merge --continue
# または
git rebase --continue

# 7. プッシュ
git push origin feature-branch --force-with-lease

Git ユーザー情報をどう設定するか？#

Git クライアントが正しいメールアドレスを設定し、あなたの GitHub ユーザーにリンクされていることを確認します。

# グローバル設定
git config --global user.name "あなたの名前"
git config --global user.email "あなたのメール@example.com"

# 現在のプロジェクトのみ設定
git config user.name "あなたの名前"
git config user.email "あなたのメール@example.com"

# 設定を確認
git config --list

最後に#

GitHub の使用規範は一見煩雑に見えますが、実際にはプロジェクトの品質とチームの協力効率を保証するための重要な基盤です。私の経験から言うと、チームが明確な Git 規範を持っているかどうかは、プロジェクトのメンテナンス性に直接反映されます。

これらの規範を導入し始めたときは、作業量が増えたように感じるかもしれませんが、慣れてしまえば、これらの規範が後のメンテナンスコストを大幅に削減することに気付くでしょう。特に、特定のバグの発生時期を遡る必要がある場合や、特定の機能の実装ロジックを迅速に理解する必要がある場合、規範的なコミットメッセージと明確なブランチ履歴が大いに役立ちます。

私の提案は:

小さなところから始める - まずはコミットメッセージの規範から始め、徐々に他の規範を導入する
ツールを活用する - Commitizen、Commitlint などのツールを使用して自動化チェックを行う
チームの合意を得る - 規範は全員が認めるものでなければならず、強制的に押し付けるものではない
継続的に最適化する - チームの実際の状況に応じて規範を調整し、完全にコピーする必要はない
模範を示す - リーダーや古参メンバーとして、率先して規範を守る

覚えておいてください、規範の目的は効率を向上させることであり、障害を作ることではありません。自分のチームに適した規範を選択し、実行し続ければ、コードの品質と協力効率が著しく向上するのを目にするでしょう。

実践の中で問題に直面したり、より良い実践経験があれば、コメント欄で交流し議論することを歓迎します。

十点还有几分钟