From 403b24d50fe2ab88fab10a0e7cff4f5a3a81b200 Mon Sep 17 00:00:00 2001 From: marketing-shibata50 Date: Sun, 20 Jul 2025 12:10:23 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20GitHub=20Pages=20=E3=82=92=E3=82=B7?= =?UTF-8?q?=E3=83=B3=E3=83=97=E3=83=AB=E8=A8=AD=E5=AE=9A=E3=81=AB=E5=A4=89?= =?UTF-8?q?=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 複雑なGitHub Actionsを削除 - ファイルをルートディレクトリに移動 - minimaテーマでシンプル構成 - 公式ドキュメント準拠の設定 🚀 GitHub Pages 標準機能のみでWebサイト構築 --- .claude/settings.local.json | 4 +- .github/workflows/pages.yml | 76 -- GITHUB_COMPLETE_GUIDE.md | 1319 ++++++++++++++++++++++++++++++ _config.yml | 33 + features/01-repository-basics.md | 413 ++++++++++ features/02-issues-management.md | 593 ++++++++++++++ index.md | 261 ++++++ 7 files changed, 2622 insertions(+), 77 deletions(-) delete mode 100644 .github/workflows/pages.yml create mode 100644 GITHUB_COMPLETE_GUIDE.md create mode 100644 _config.yml create mode 100644 features/01-repository-basics.md create mode 100644 features/02-issues-management.md create mode 100644 index.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json index e4a6770..9e75fee 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -1,7 +1,9 @@ { "permissions": { "allow": [ - "Bash(git add:*)" + "Bash(git add:*)", + "Bash(git commit:*)", + "WebFetch(domain:docs.github.com)" ], "deny": [] } diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml deleted file mode 100644 index cd5e8a7..0000000 --- a/.github/workflows/pages.yml +++ /dev/null @@ -1,76 +0,0 @@ -name: Deploy GitHub Pages - -on: - push: - branches: [ main ] - paths: - - 'docs/**' - - '.github/workflows/pages.yml' - - # 手動実行を許可 - workflow_dispatch: - -# GitHub Pagesデプロイのための権限設定 -permissions: - contents: read - pages: write - id-token: write - -# 同時実行の制御 -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - # ビルドジョブ - build: - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Ruby - uses: ruby/setup-ruby@v1 - with: - ruby-version: '3.1' - bundler-cache: true - - - name: Setup Pages - id: pages - uses: actions/configure-pages@v3 - - - name: Install dependencies - run: | - cd docs - bundle install - - - name: Build site - run: | - cd docs - bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" - env: - JEKYLL_ENV: production - - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: docs/_site - - # デプロイジョブ - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: build - - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 - - - name: Notify deployment success - run: | - echo "🎉 サイトが正常にデプロイされました!" - echo "📍 URL: ${{ steps.deployment.outputs.page_url }}" \ No newline at end of file diff --git a/GITHUB_COMPLETE_GUIDE.md b/GITHUB_COMPLETE_GUIDE.md new file mode 100644 index 0000000..75811b6 --- /dev/null +++ b/GITHUB_COMPLETE_GUIDE.md @@ -0,0 +1,1319 @@ +# 📖 GitHub完全活用ガイド + +> 外部ツールに依存せず、GitHub一つで開発業務を完結させるための網羅的解説書 + +## 🎯 このガイドの目的 + +- **GitHub機能の全体像を把握**し、どの場面でどの機能を使うかを理解 +- **外部ツール（Jira、Jenkins、Confluence等）を使わずに開発を完結**させる方法を習得 +- **実務ですぐに使える設定例とベストプラクティス**を提供 +- **コスト削減と開発効率向上**を同時に実現 + +--- + +## 📚 目次 + +### 第1章: [GitHub機能全体マップ](#第1章-github機能全体マップ) +### 第2章: [リポジトリ管理の完全活用](#第2章-リポジトリ管理の完全活用) +### 第3章: [Issues - プロジェクト管理の核](#第3章-issues---プロジェクト管理の核) +### 第4章: [Pull Request - コードレビューとコラボレーション](#第4章-pull-request---コードレビューとコラボレーション) +### 第5章: [GitHub Projects - タスク・プロジェクト管理](#第5章-github-projects---タスクプロジェクト管理) +### 第6章: [GitHub Actions - CI/CD自動化](#第6章-github-actions---cicd自動化) +### 第7章: [セキュリティ機能 - 品質・安全性の確保](#第7章-セキュリティ機能---品質安全性の確保) +### 第8章: [GitHub Pages - ドキュメント・サイト公開](#第8章-github-pages---ドキュメントサイト公開) +### 第9章: [外部ツール代替戦略](#第9章-外部ツール代替戦略) +### 第10章: [実務ケーススタディ](#第10章-実務ケーススタディ) + +--- + +## 第1章: GitHub機能全体マップ + +### 🗺️ GitHub機能の全体像 + +```mermaid +mindmap + root((GitHub)) + (リポジトリ管理) + [コード管理] + [ブランチ戦略] + [リリース管理] + [コラボレーター管理] + (プロジェクト管理) + [Issues] + [Projects V2] + [マイルストーン] + [ラベル管理] + (コードレビュー) + [Pull Request] + [Code Review] + [Draft PR] + [Suggested Changes] + (自動化) + [GitHub Actions] + [Webhooks] + [Apps] + [API] + (セキュリティ) + [Dependabot] + [Code Scanning] + [Secret Scanning] + [Branch Protection] + (公開・共有) + [GitHub Pages] + [Releases] + [Packages] + [Gists] + (コミュニケーション) + [Discussions] + [Wiki] + [Notifications] + [Teams] +``` + +### 📊 機能重要度マトリックス + +| 機能 | 重要度 | 習得難易度 | 外部ツール代替度 | 実装優先度 | +|------|--------|------------|------------------|------------| +| **Issues** | ⭐⭐⭐⭐⭐ | ⭐⭐ | 95% | 🔥 最優先 | +| **Pull Request** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | 90% | 🔥 最優先 | +| **GitHub Actions** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 100% | 🔥 最優先 | +| **Projects V2** | ⭐⭐⭐⭐ | ⭐⭐⭐ | 85% | 🔶 高 | +| **Branch Protection** | ⭐⭐⭐⭐ | ⭐⭐ | 80% | 🔶 高 | +| **GitHub Pages** | ⭐⭐⭐ | ⭐⭐ | 70% | 🔷 中 | +| **Code Scanning** | ⭐⭐⭐⭐ | ⭐⭐⭐ | 90% | 🔷 中 | +| **Discussions** | ⭐⭐⭐ | ⭐ | 60% | ⚪ 低 | + +--- + +## 第2章: リポジトリ管理の完全活用 + +### 🏗️ リポジトリ構造のベストプラクティス + +#### 推奨ディレクトリ構造 +``` +your-project/ +├── .github/ +│ ├── workflows/ # GitHub Actions +│ ├── ISSUE_TEMPLATE/ # Issueテンプレート +│ ├── PULL_REQUEST_TEMPLATE.md +│ ├── CODEOWNERS # コードレビュー担当者 +│ ├── SECURITY.md # セキュリティポリシー +│ └── FUNDING.yml # スポンサー設定 +├── docs/ # ドキュメント +├── src/ # ソースコード +├── tests/ # テストコード +├── .gitignore +├── README.md +├── LICENSE +└── CHANGELOG.md +``` + +### 🌳 ブランチ戦略の実装 + +#### GitHub Flow（推奨） +```bash +# 1. mainブランチから新機能ブランチを作成 +git checkout main +git pull origin main +git checkout -b feature/user-authentication + +# 2. 開発・コミット +git add . +git commit -m "feat(auth): add login functionality" + +# 3. プッシュしてPull Request作成 +git push origin feature/user-authentication +gh pr create --title "Add user authentication" --body "Implements login/logout functionality" + +# 4. レビュー後、mainにマージ +# （GitHub Web UIまたは gh pr merge） + +# 5. ローカルブランチクリーンアップ +git checkout main +git pull origin main +git branch -d feature/user-authentication +``` + +#### Git Flow（複雑なプロジェクト用） +```bash +# 開発ブランチの維持 +git checkout -b develop + +# フィーチャーブランチ +git checkout -b feature/payment-system develop + +# リリースブランチ +git checkout -b release/v1.0.0 develop + +# ホットフィックス +git checkout -b hotfix/security-fix main +``` + +### 🏷️ タグ・リリース管理 + +#### セマンティックバージョニング +```bash +# メジャー版更新（破壊的変更） +git tag -a v2.0.0 -m "Version 2.0.0 - API breaking changes" + +# マイナー版更新（新機能追加） +git tag -a v1.1.0 -m "Version 1.1.0 - New authentication system" + +# パッチ版更新（バグ修正） +git tag -a v1.0.1 -m "Version 1.0.1 - Security fixes" + +# リモートにプッシュ +git push origin --tags +``` + +#### 自動リリースノート設定 +```yaml +# .github/release.yml +changelog: + exclude: + labels: + - ignore-for-release + - dependencies + categories: + - title: 🚨 Breaking Changes + labels: + - breaking-change + - major + - title: 🎉 New Features + labels: + - enhancement + - feature + - title: 🐛 Bug Fixes + labels: + - bug + - fix + - title: 📚 Documentation + labels: + - documentation + - title: 🔧 Maintenance + labels: + - maintenance + - chore +``` + +--- + +## 第3章: Issues - プロジェクト管理の核 + +### 🎫 Issues活用の全体戦略 + +#### Jiraの完全代替を実現するIssue運用 +```markdown +# Issue種別をラベルで分類 +🐛 bug - バグ報告 +✨ enhancement - 新機能要望 +📚 documentation - ドキュメント +❓ question - 質問・サポート +🔧 maintenance - メンテナンス + +# 優先度管理 +🔴 priority:critical - 緊急（即座に対応） +🟠 priority:high - 高（1週間以内） +🟡 priority:medium - 中（2週間以内） +🟢 priority:low - 低（1ヶ月以内） + +# ステータス管理 +📋 status:new - 新規作成 +👀 status:triaged - トリアージ済み +🔄 status:in-progress - 作業中 +⏸️ status:blocked - ブロック中 +✅ status:resolved - 解決済み +``` + +#### 実用的なIssueテンプレート + +**バグ報告用** +```yaml +# .github/ISSUE_TEMPLATE/bug_report.yml +name: 🐛 バグ報告 +description: バグを報告してください +title: "[BUG] " +labels: ["bug", "needs-triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + バグ報告ありがとうございます。以下の情報を詳しく入力してください。 + + - type: textarea + id: bug-description + attributes: + label: 🐛 バグの詳細 + description: 何が起こっているか詳しく説明してください + placeholder: | + 例: ログインボタンをクリックしても、ページが遷移しない + validations: + required: true + + - type: textarea + id: steps-to-reproduce + attributes: + label: 🔄 再現手順 + description: バグを再現する手順を順番に記載してください + placeholder: | + 1. ホームページにアクセス + 2. "ログイン"ボタンをクリック + 3. メールアドレスとパスワードを入力 + 4. "ログイン"ボタンをクリック + 5. エラーが発生 + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: ✅ 期待される動作 + description: 本来はどうなるべきかを説明してください + placeholder: ログイン後、ダッシュボードページに遷移する + validations: + required: true + + - type: textarea + id: environment + attributes: + label: 🖥️ 環境情報 + description: 環境に関する詳細情報 + placeholder: | + - OS: macOS 13.0 + - ブラウザ: Chrome 108.0 + - アプリバージョン: v1.2.3 + - その他: + validations: + required: true + + - type: textarea + id: additional-context + attributes: + label: 📋 追加情報 + description: スクリーンショット、ログ、その他関連情報 + placeholder: エラーメッセージ、スクリーンショットなど + + - type: checkboxes + id: terms + attributes: + label: ✅ 確認事項 + options: + - label: 同様のIssueが既に報告されていないことを確認しました + required: true + - label: 最新バージョンで問題が発生することを確認しました + required: true +``` + +#### 高度なIssue管理機能 + +**自動ラベリング** +```yaml +# .github/workflows/label-issues.yml +name: Auto Label Issues +on: + issues: + types: [opened] + +jobs: + label: + runs-on: ubuntu-latest + steps: + - name: Label based on title + uses: actions/github-script@v6 + with: + script: | + const title = context.payload.issue.title.toLowerCase(); + const labels = []; + + if (title.includes('bug') || title.includes('error')) { + labels.push('bug'); + } + if (title.includes('feature') || title.includes('add')) { + labels.push('enhancement'); + } + if (title.includes('security')) { + labels.push('security', 'priority:high'); + } + if (title.includes('performance')) { + labels.push('performance'); + } + + if (labels.length > 0) { + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.issue.number, + labels: labels + }); + } +``` + +--- + +## 第4章: Pull Request - コードレビューとコラボレーション + +### 🔄 Pull Requestワークフローの最適化 + +#### 効果的なPRテンプレート +```markdown +# .github/pull_request_template.md +## 📋 変更内容の要約 + + + +## 🎯 関連Issue + +Fixes #(issue番号) +Closes #(issue番号) +Related to #(issue番号) + +## 🔄 変更の種類 + +- [ ] 🐛 バグ修正 +- [ ] ✨ 新機能 +- [ ] 💥 破壊的変更 +- [ ] 📚 ドキュメント更新 +- [ ] 🎨 コードスタイル改善（機能に影響なし） +- [ ] ♻️ リファクタリング +- [ ] ⚡ パフォーマンス改善 +- [ ] ✅ テスト追加・修正 +- [ ] 🔧 ビルドシステム・設定変更 + +## 🧪 テスト方法 + + + +- [ ] 単体テスト追加・実行 +- [ ] 統合テスト追加・実行 +- [ ] 手動テスト実行 +- [ ] 既存テストがすべて通ることを確認 + +### テスト手順 +1. +2. +3. + +## 📸 スクリーンショット（UI変更の場合） + + + +| Before | After | +|--------|-------| +| | | + +## ✅ チェックリスト + +- [ ] コードが自己文書化されており、理解しやすい +- [ ] 適切なコメントが追加されている +- [ ] ドキュメントが更新されている +- [ ] テストが追加・更新されている +- [ ] 破壊的変更がある場合、CHANGELOGに記載されている +- [ ] セキュリティの観点で問題がない + +## 📝 追加メモ + + +``` + +#### Code Review のベストプラクティス + +**レビュー観点チェックリスト** +```markdown +### 🔍 機能性 +- [ ] 要件を満たしているか +- [ ] エッジケースが考慮されているか +- [ ] エラーハンドリングが適切か + +### 🏗️ アーキテクチャ +- [ ] 設計方針に沿っているか +- [ ] 適切な責務分離がされているか +- [ ] 再利用性が考慮されているか + +### 🎯 パフォーマンス +- [ ] 不要な処理がないか +- [ ] メモリ使用量は適切か +- [ ] データベースクエリは最適化されているか + +### 🔒 セキュリティ +- [ ] 入力値検証が適切か +- [ ] 権限チェックがされているか +- [ ] 機密情報が漏洩しないか + +### 🧹 保守性 +- [ ] コードが読みやすいか +- [ ] 適切な命名がされているか +- [ ] コメントが適切か + +### ✅ テスト +- [ ] テストカバレッジは十分か +- [ ] テストケースは適切か +- [ ] CIが通っているか +``` + +#### Advanced PR機能の活用 + +**Draft PRの活用** +```bash +# 作業中のコードでフィードバックを得る +gh pr create --draft --title "WIP: ユーザー認証機能" --body "作業中のコードです。アプローチについてフィードバックをお願いします" + +# レビュー準備完了時 +gh pr ready # DraftからReadyに変更 +``` + +**Suggested Changes機能** +```markdown +# レビューコメントで具体的な修正案を提示 +```suggestion +// 修正前のコード +const user = users.find(u => u.id === userId); + +// 修正後のコード +const user = users.find(u => u.id === userId) ?? null; +``` + +--- + +## 第5章: GitHub Projects - タスク・プロジェクト管理 + +### 📊 GitHub Projects V2 の完全活用 + +#### Jira代替としてのProjects設定 + +**プロジェクトボード構成例** +```markdown +## ボード設定 + +### 📋 ビュー設定 +1. **カンバンビュー** - 日常的な作業管理 + - Todo | In Progress | In Review | Done + +2. **スプリントビュー** - 時間軸での管理 + - 週別 | 月別のスプリント + +3. **ロードマップビュー** - 長期計画 + - 四半期別のマイルストーン + +4. **優先度ビュー** - 優先度順の作業 + - Critical | High | Medium | Low + +### 🏷️ カスタムフィールド設定 +- **Status**: Single select (Todo, In Progress, Review, Done) +- **Priority**: Single select (Critical, High, Medium, Low) +- **Size**: Number (ストーリーポイント) +- **Epic**: Text (関連するエピック) +- **Sprint**: Text (スプリント名) +- **Assignee**: People (担当者) +- **Labels**: Multiple select (技術分野) +``` + +#### プロジェクト自動化の設定 + +**Issues の自動追加** +```yaml +# プロジェクト自動化ルール設定例 + +# 新しいIssueを自動でプロジェクトに追加 +when: Issue created +then: Add to project "Development Board" + Set Status to "Todo" + Set Priority based on labels + +# PRがマージされたらIssueを完了に +when: Pull request merged +then: Find linked issues + Set Status to "Done" + Add comment "Completed in PR #XXX" + +# 高優先度のIssueに自動アサイン +when: Issue labeled "priority:high" +then: Assign to @tech-lead + Set Status to "Todo" + Add to "High Priority" view +``` + +### 📈 進捗管理とレポート + +#### ダッシュボード作成 +```markdown +### 📊 KPI ダッシュボード + +#### チーム生産性指標 +- **Velocity**: 週/月あたりの完了ストーリーポイント +- **Cycle Time**: IssueからPRマージまでの平均時間 +- **Throughput**: 完了したIssue数/期間 +- **WIP**: 同時進行中のタスク数 + +#### 品質指標 +- **Defect Rate**: 本番バグ数/リリース +- **Code Review Time**: PR作成からマージまでの時間 +- **Test Coverage**: テストカバレッジ率 +- **Technical Debt**: 未解決の技術的課題数 + +#### チーム健全性 +- **Burnout Index**: 個人の作業量バランス +- **Knowledge Sharing**: ペアプロ・レビュー参加率 +- **Documentation**: ドキュメント更新頻度 +``` + +--- + +## 第6章: GitHub Actions - CI/CD自動化 + +### ⚙️ Jenkins完全代替のワークフロー + +#### 基本CI/CDパイプライン +```yaml +# .github/workflows/ci-cd.yml +name: CI/CD Pipeline + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +env: + NODE_VERSION: '18' + PYTHON_VERSION: '3.11' + +jobs: + # 1. コード品質チェック + code-quality: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Lint + run: npm run lint + + - name: Type check + run: npm run type-check + + - name: Format check + run: npm run format:check + + # 2. テスト実行 + test: + runs-on: ubuntu-latest + strategy: + matrix: + node-version: [16, 18, 20] + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run tests + run: npm run test:coverage + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v3 + with: + file: ./coverage/lcov.info + + # 3. セキュリティスキャン + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Run security audit + run: npm audit --audit-level moderate + + - name: Run CodeQL Analysis + uses: github/codeql-action/analyze@v2 + with: + languages: javascript + + # 4. ビルド + build: + runs-on: ubuntu-latest + needs: [code-quality, test, security] + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Build + run: npm run build + + - name: Upload build artifacts + uses: actions/upload-artifact@v3 + with: + name: build-files + path: dist/ + + # 5. デプロイ（mainブランチのみ） + deploy: + runs-on: ubuntu-latest + needs: build + if: github.ref == 'refs/heads/main' + environment: production + steps: + - uses: actions/checkout@v4 + + - name: Download build artifacts + uses: actions/download-artifact@v3 + with: + name: build-files + path: dist/ + + - name: Deploy to production + run: | + # デプロイスクリプト実行 + echo "Deploying to production..." + # 実際のデプロイコマンド + + - name: Notify deployment + uses: 8398a7/action-slack@v3 + with: + status: ${{ job.status }} + text: "Production deployment completed" + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }} +``` + +#### 高度な自動化パターン + +**自動バージョニング** +```yaml +# .github/workflows/auto-version.yml +name: Auto Version and Release + +on: + push: + branches: [ main ] + +jobs: + version-and-release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Determine version bump + id: version + run: | + # コミットメッセージから版数を決定 + if [[ "${{ github.event.head_commit.message }}" =~ ^feat(\(.+\))?!: ]]; then + echo "bump=major" >> $GITHUB_OUTPUT + elif [[ "${{ github.event.head_commit.message }}" =~ ^feat(\(.+\))?: ]]; then + echo "bump=minor" >> $GITHUB_OUTPUT + else + echo "bump=patch" >> $GITHUB_OUTPUT + fi + + - name: Bump version + run: npm version ${{ steps.version.outputs.bump }} + + - name: Push changes + run: | + git push origin main + git push origin --tags + + - name: Create release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ steps.version.outputs.new_tag }} + release_name: Release ${{ steps.version.outputs.new_tag }} + draft: false + prerelease: false +``` + +**依存関係自動更新** +```yaml +# .github/workflows/dependency-update.yml +name: Dependency Update + +on: + schedule: + - cron: '0 9 * * 1' # 毎週月曜日 9:00 + +jobs: + update-dependencies: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Update dependencies + run: | + npx npm-check-updates -u + npm install + + - name: Run tests + run: npm test + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v5 + with: + token: ${{ secrets.GITHUB_TOKEN }} + commit-message: 'chore: update dependencies' + title: '🔄 Weekly dependency update' + body: | + 自動的に依存関係を更新しました。 + + - テストが正常に通ることを確認済み + - 破壊的変更がないかレビューをお願いします + branch: update-dependencies + delete-branch: true +``` + +--- + +## 第7章: セキュリティ機能 - 品質・安全性の確保 + +### 🔒 SonarQube代替のセキュリティ体制 + +#### GitHub Advanced Security の活用 + +**Dependabot設定** +```yaml +# .github/dependabot.yml +version: 2 +updates: + # npm依存関係の監視 + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + time: "09:00" + open-pull-requests-limit: 10 + reviewers: + - "security-team" + assignees: + - "tech-lead" + commit-message: + prefix: "chore" + include: "scope" + labels: + - "dependencies" + - "security" + + # Docker依存関係の監視 + - package-ecosystem: "docker" + directory: "/" + schedule: + interval: "weekly" + + # GitHub Actions依存関係の監視 + - package-ecosystem: "github-actions" + directory: "/.github/workflows" + schedule: + interval: "monthly" +``` + +**Code Scanning設定** +```yaml +# .github/workflows/security-scan.yml +name: Security Scanning + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + schedule: + - cron: '0 6 * * 1' + +jobs: + codeql: + name: CodeQL Analysis + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + strategy: + matrix: + language: [ 'javascript', 'typescript', 'python' ] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + languages: ${{ matrix.language }} + config-file: ./.github/codeql/codeql-config.yml + + - name: Autobuild + uses: github/codeql-action/autobuild@v2 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 + + secret-scan: + name: Secret Scanning + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: GitLeaks Scan + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + dependency-check: + name: Dependency Vulnerability Check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Install dependencies + run: npm ci + + - name: Audit dependencies + run: | + npm audit --audit-level moderate + npm audit --json > audit-results.json + + - name: Upload audit results + uses: actions/upload-artifact@v3 + with: + name: audit-results + path: audit-results.json +``` + +#### Branch Protection Rules + +**高度な保護設定** +```bash +# GitHub CLI でbranch protection設定 +gh api repos/:owner/:repo/branches/main/protection \ + --method PUT \ + --field required_status_checks='{"strict":true,"contexts":["ci/test","ci/lint","ci/security"]}' \ + --field enforce_admins=true \ + --field required_pull_request_reviews='{"required_approving_review_count":2,"dismiss_stale_reviews":true,"require_code_owner_reviews":true,"require_last_push_approval":true}' \ + --field restrictions=null \ + --field required_linear_history=true \ + --field allow_force_pushes=false \ + --field allow_deletions=false \ + --field required_conversation_resolution=true +``` + +--- + +## 第8章: GitHub Pages - ドキュメント・サイト公開 + +### 📖 Confluence代替のドキュメント戦略 + +#### 自動ドキュメント生成・公開 + +**ドキュメントサイト自動生成** +```yaml +# .github/workflows/docs.yml +name: Documentation + +on: + push: + branches: [ main ] + paths: + - 'docs/**' + - 'src/**' + - '*.md' + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + permissions: + contents: read + pages: write + id-token: write + + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Install dependencies + run: npm ci + + - name: Generate API documentation + run: | + # JSDoc またはTypedocでAPI文書生成 + npm run docs:api + + - name: Build documentation site + run: | + # VuePress, Docusaurus, or MkDocsでサイトビルド + npm run docs:build + + - name: Setup Pages + uses: actions/configure-pages@v3 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: './docs/.vitepress/dist' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 +``` + +#### 多言語ドキュメント対応 +```yaml +# ドキュメント構造例 +docs/ +├── .vitepress/ +│ ├── config.js +│ └── theme/ +├── en/ +│ ├── guide/ +│ ├── api/ +│ └── examples/ +├── ja/ +│ ├── guide/ +│ ├── api/ +│ └── examples/ +└── README.md +``` + +--- + +## 第9章: 外部ツール代替戦略 + +### 🔄 移行戦略マトリックス + +#### 主要ツールの段階的移行 + +| 移行段階 | 対象ツール | GitHub代替機能 | 実装期間 | 注意点 | +|----------|------------|----------------|----------|--------| +| **Phase 1** | Jira | Issues + Projects V2 | 2-4週間 | カスタムフィールドの再設計が必要 | +| **Phase 2** | Jenkins | GitHub Actions | 3-6週間 | 既存パイプラインの段階的移行 | +| **Phase 3** | Confluence | GitHub Pages + Wiki | 2-3週間 | コンテンツ移行とURL再設計 | +| **Phase 4** | SonarQube | Advanced Security | 1-2週間 | セキュリティポリシーの調整 | +| **Phase 5** | Slack (開発) | Discussions + Webhooks | 1週間 | 通知ルールの再設定 | + +#### Jira → GitHub Issues 移行詳細 + +**データ移行スクリプト例** +```python +# jira_to_github_migration.py +import requests +import json +from datetime import datetime + +class JiraToGitHubMigrator: + def __init__(self, jira_url, jira_auth, github_token, github_repo): + self.jira_url = jira_url + self.jira_auth = jira_auth + self.github_token = github_token + self.github_repo = github_repo + + def migrate_issues(self): + # Jira IssuesをGitHub Issuesに移行 + jira_issues = self.fetch_jira_issues() + + for jira_issue in jira_issues: + github_issue = self.convert_issue(jira_issue) + self.create_github_issue(github_issue) + + def convert_issue(self, jira_issue): + # Jira形式からGitHub形式に変換 + return { + 'title': jira_issue['fields']['summary'], + 'body': self.convert_description(jira_issue['fields']['description']), + 'labels': self.map_labels(jira_issue['fields']), + 'assignees': self.map_assignees(jira_issue['fields']['assignee']), + 'milestone': self.map_milestone(jira_issue['fields']['fixVersions']) + } + + def map_labels(self, fields): + # JiraラベルをGitHubラベルにマッピング + label_mapping = { + 'Bug': 'bug', + 'Task': 'enhancement', + 'Story': 'feature', + 'Epic': 'epic', + 'High': 'priority:high', + 'Medium': 'priority:medium', + 'Low': 'priority:low' + } + + labels = [] + if fields.get('issuetype'): + labels.append(label_mapping.get(fields['issuetype']['name'], 'other')) + + if fields.get('priority'): + labels.append(label_mapping.get(fields['priority']['name'], 'priority:medium')) + + return labels +``` + +#### コスト比較分析 + +**年間コスト比較（100人チーム想定）** +```markdown +### 従来の外部ツール構成 +- Jira: $7,000/年 (100ユーザー) +- Jenkins: $15,000/年 (自社運用コスト) +- Confluence: $5,000/年 (100ユーザー) +- SonarQube: $10,000/年 (Enterprise) +- Slack: $8,000/年 (Pro plan) +**合計: $45,000/年** + +### GitHub統合構成 +- GitHub Enterprise: $21,000/年 (100ユーザー) +- Actions minutes: $2,000/年 (追加分) +- Advanced Security: $5,000/年 (100ユーザー) +- Storage: $500/年 +**合計: $28,500/年** + +**年間削減額: $16,500 (37%削減)** +``` + +--- + +## 第10章: 実務ケーススタディ + +### 📝 実際の開発フローパターン + +#### ケース1: スタートアップの迅速な開発 + +**チーム構成**: 5名（フルスタック） +**要件**: 迅速なプロダクト開発、最小限のツール、コスト削減 + +```markdown +### 採用したGitHub構成 + +1. **リポジトリ戦略** + - モノリポ構成（フロント・バック統合） + - GitHub Flow採用 + - main ブランチのみ保護 + +2. **Issue管理** + - 簡素化されたラベル体系（bug, feature, urgent のみ） + - 週次スプリントをマイルストーンで管理 + - 全員がすべてのIssueを見る文化 + +3. **自動化** + - 基本的なCI（lint, test, build） + - 自動デプロイ（Vercel連携） + - 依存関係の週次自動更新 + +### 成果 +- 外部ツール費用: 月額$0 → 年間$60,000削減 +- セットアップ時間: 1日で完了 +- 開発サイクル: 2週間 → 1週間に短縮 +``` + +#### ケース2: エンタープライズの段階的移行 + +**チーム構成**: 50名（複数チーム） +**要件**: 既存ツールからの段階的移行、ガバナンス重視 + +```markdown +### 移行ステップ + +#### Phase 1: Jira → GitHub Issues (3ヶ月) +1. **準備期間** (1ヶ月) + - ラベル体系の設計 + - Issueテンプレートの作成 + - 移行ツールの開発 + +2. **パイロット運用** (1ヶ月) + - 1チームでの試験運用 + - フィードバック収集と改善 + - トレーニング資料作成 + +3. **全社展開** (1ヶ月) + - 全チームへの段階的移行 + - データ移行の実行 + - サポート体制の確立 + +#### Phase 2: Jenkins → GitHub Actions (4ヶ月) +1. **アセスメント** (1ヶ月) + - 既存パイプラインの棚卸し + - Actions移行計画策定 + - セキュリティ要件の確認 + +2. **移行実装** (2ヶ月) + - 段階的なワークフロー移行 + - 並行運用による検証 + - パフォーマンス最適化 + +3. **切り替え完了** (1ヶ月) + - 旧システムの停止 + - 監視・アラートの移行 + - 運用手順の更新 + +### 成果 +- 年間運用コスト: 40%削減 +- デプロイ頻度: 週1回 → 日次に向上 +- 障害対応時間: 50%短縮 +``` + +#### ケース3: オープンソースプロジェクト + +**プロジェクト規模**: コントリビューター100名 +**要件**: グローバル協業、透明性、コミュニティ形成 + +```markdown +### GitHub機能フル活用構成 + +1. **コミュニティ管理** + - Discussions でQ&A、提案、雑談 + - Issue/PRテンプレートで貢献ハードルを下げる + - CODEOWNERSで責任分散 + +2. **開発プロセス** + - 詳細なコントリビューションガイド + - 多段階のレビュープロセス + - 自動化された品質チェック + +3. **プロジェクト管理** + - 公開ロードマップ（Projects） + - マイルストーンベースのリリース計画 + - 透明な意思決定プロセス + +### 特徴的な設定 +- **Sponsor機能**: 資金調達とサステナビリティ +- **Security Policy**: 脆弱性報告の仕組み +- **Actions Marketplace**: 再利用可能なワークフロー公開 +- **Pages**: ドキュメント・ブログ・ショーケース + +### 成果 +- コントリビューター数: 3倍増加 +- Issue解決率: 85%向上 +- リリース頻度: 月次 → 週次 +``` + +--- + +## 🔧 付録: 実装チェックリスト + +### Phase 1: 基礎設定（1週間） + +```markdown +#### リポジトリ設定 +- [ ] .github/ディレクトリ作成 +- [ ] README.md充実 +- [ ] .gitignore設定 +- [ ] LICENSE追加 +- [ ] SECURITY.md作成 + +#### Issue管理 +- [ ] ラベル体系設計・作成 +- [ ] Issueテンプレート作成 +- [ ] マイルストーン設定 +- [ ] 初期Issueの作成 + +#### ブランチ戦略 +- [ ] ブランチ保護ルール設定 +- [ ] develop/mainブランチ構成 +- [ ] マージポリシー決定 +``` + +### Phase 2: 自動化導入（2週間） + +```markdown +#### GitHub Actions +- [ ] 基本CIワークフロー +- [ ] 自動テスト実行 +- [ ] コード品質チェック +- [ ] セキュリティスキャン + +#### Pull Request +- [ ] PRテンプレート作成 +- [ ] レビューアサイン自動化 +- [ ] ステータスチェック設定 +- [ ] 自動マージ設定 +``` + +### Phase 3: 高度な機能（3週間） + +```markdown +#### Projects活用 +- [ ] プロジェクトボード作成 +- [ ] カスタムフィールド設定 +- [ ] 自動化ルール設定 +- [ ] ダッシュボード構築 + +#### セキュリティ強化 +- [ ] Dependabot設定 +- [ ] Secret scanning有効化 +- [ ] Advanced Security設定 +- [ ] 監査ログ設定 + +#### ドキュメント・公開 +- [ ] GitHub Pages設定 +- [ ] 自動ドキュメント生成 +- [ ] Wiki整備 +- [ ] Discussions設定 +``` + +--- + +## 🎯 まとめ + +この完全ガイドにより、**GitHub一つで完結する開発環境**を構築できます： + +### 🔥 即座に得られる効果 +- **コスト削減**: 年間数万〜数十万円の削減 +- **学習コスト削減**: 統一されたプラットフォームで習得時間短縮 +- **開発効率向上**: シームレスな連携による生産性向上 + +### 📈 中長期的な価値 +- **スケーラビリティ**: チーム拡大への対応力 +- **保守性**: 一元管理による運用負荷削減 +- **イノベーション**: 最新機能への迅速なアクセス + +### 🚀 成功への鍵 +1. **段階的導入**: 一度にすべてを変えず、段階的に移行 +2. **チーム教育**: 十分なトレーニングとサポート体制 +3. **継続的改善**: 定期的な見直しと最適化 + +**GitHub機能をフル活用し、外部ツールに依存しない効率的な開発環境を構築しましょう！** \ No newline at end of file diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..a377a19 --- /dev/null +++ b/_config.yml @@ -0,0 +1,33 @@ +# GitHub研究ツール - シンプル設定 + +title: "GitHub完全活用ガイド" +description: "外部ツールに依存せず、GitHub一つで開発業務を完結させるための網羅的解説書" + +# GitHub Pages標準テーマ +theme: minima + +# GitHub情報 +github_username: marketing-shibata50 +repository: marketing-shibata50/github-research-tool + +# サイト設定 +lang: ja +timezone: Asia/Tokyo + +# プラグイン（GitHub Pages標準） +plugins: + - jekyll-feed + - jekyll-sitemap + +# Markdown設定 +markdown: kramdown +highlighter: rouge + +# 除外ファイル +exclude: + - docs/ + - practice-project/ + - tools/ + - examples/ + - test + - README.md \ No newline at end of file diff --git a/features/01-repository-basics.md b/features/01-repository-basics.md new file mode 100644 index 0000000..1236135 --- /dev/null +++ b/features/01-repository-basics.md @@ -0,0 +1,413 @@ +# 📁 GitHub リポジトリ基礎 + +GitHubリポジトリの基本的な機能と操作方法を網羅的に解説します。 + +## 🎯 学習目標 + +- リポジトリの作成から管理まで一連の操作をマスター +- ブランチ戦略の理解と実践 +- タグとリリースの効果的な活用 +- 外部ツールとの違いを理解 + +## 📚 目次 + +1. [リポジトリ作成・初期設定](#1-リポジトリ作成初期設定) +2. [ブランチ管理](#2-ブランチ管理) +3. [コミット管理](#3-コミット管理) +4. [タグ・リリース管理](#4-タグリリース管理) +5. [リポジトリ設定](#5-リポジトリ設定) +6. [外部ツールとの比較](#6-外部ツールとの比較) + +--- + +## 1. リポジトリ作成・初期設定 + +### 🚀 新規リポジトリ作成 + +#### Web UIでの作成 +```markdown +1. GitHub.com にログイン +2. 右上の「+」→「New repository」 +3. 必要な設定を入力： + - Repository name: プロジェクト名 + - Description: プロジェクトの説明 + - Public/Private: 公開範囲 + - README: 初期化オプション + - .gitignore: 言語・フレームワーク選択 + - License: ライセンス選択 +``` + +#### CLI (GitHub CLI) での作成 +```bash +# 基本的なリポジトリ作成 +gh repo create my-project --public --description "プロジェクトの説明" + +# README、.gitignore、ライセンス付きで作成 +gh repo create my-project --public --add-readme --gitignore Node --license MIT + +# ローカルディレクトリから作成 +gh repo create --source=. --public --push +``` + +### 🔧 初期設定のベストプラクティス + +#### 1. README.md の充実 +```markdown +# プロジェクト名 + +## 概要 +プロジェクトの目的と機能の簡潔な説明 + +## インストール +```bash +npm install +``` + +## 使用方法 +基本的な使い方のサンプル + +## 貢献方法 +コントリビューションガイドライン + +## ライセンス +ライセンス情報 +``` + +#### 2. .gitignore の設定 +```bash +# GitHub提供のテンプレートを使用 +curl -s https://api.github.com/gitignore/templates/Node > .gitignore + +# 独自の設定を追加 +echo "# Custom ignores +*.log +.env.local +dist/" >> .gitignore +``` + +--- + +## 2. ブランチ管理 + +### 🌳 ブランチ戦略 + +#### Git Flow +```mermaid +graph LR + A[main] --> B[develop] + B --> C[feature/login] + B --> D[feature/payment] + C --> B + D --> B + B --> E[release/v1.0] + E --> A + E --> B + A --> F[hotfix/security-fix] + F --> A + F --> B +``` + +#### GitHub Flow (推奨) +```mermaid +graph LR + A[main] --> B[feature/new-component] + B --> C[Pull Request] + C --> D[Code Review] + D --> E[Merge to main] + E --> F[Deploy] +``` + +### 📋 ブランチ操作 + +#### ローカルでのブランチ作成 +```bash +# 新しいブランチを作成して切り替え +git checkout -b feature/user-authentication + +# または（Git 2.23以降） +git switch -c feature/user-authentication + +# リモートにプッシュ +git push -u origin feature/user-authentication +``` + +#### GitHub Web UIでのブランチ作成 +```markdown +1. リポジトリページで「main」ブランチ選択部分をクリック +2. 新しいブランチ名を入力 +3. 「Create branch: branch-name from main」をクリック +``` + +#### GitHub CLI でのブランチ作成 +```bash +# ブランチ作成とチェックアウト +gh repo fork --clone +cd repository-name +git checkout -b feature/new-feature + +# 変更をプッシュ +git push origin feature/new-feature +``` + +### 🛡️ ブランチ保護設定 + +#### main ブランチの保護 +```markdown +1. Settings → Branches +2. 「Add rule」をクリック +3. Branch name pattern: `main` +4. 設定項目： + ✅ Require a pull request before merging + ✅ Require approvals (推奨: 1人以上) + ✅ Dismiss stale PR approvals when new commits are pushed + ✅ Require status checks to pass before merging + ✅ Require branches to be up to date before merging + ✅ Require conversation resolution before merging + ✅ Restrict pushes that create files larger than 100MB +``` + +--- + +## 3. コミット管理 + +### 📝 効果的なコミットメッセージ + +#### Conventional Commits 形式 +```bash +# 形式: [optional scope]: + +git commit -m "feat(auth): add user authentication system" +git commit -m "fix(api): resolve timeout issue in user endpoint" +git commit -m "docs: update README with installation guide" +git commit -m "refactor(utils): simplify date formatting function" +``` + +#### タイプ一覧 +- `feat`: 新機能 +- `fix`: バグ修正 +- `docs`: ドキュメント変更 +- `style`: コードスタイル変更（機能に影響なし） +- `refactor`: リファクタリング +- `test`: テスト追加・修正 +- `chore`: ビルド・設定ファイル変更 + +### 🔍 コミット履歴の管理 + +#### 履歴の確認 +```bash +# グラフィカルな履歴表示 +git log --graph --oneline --all + +# 特定のファイルの履歴 +git log --follow -- path/to/file + +# GitHub CLI での履歴確認 +gh repo view --web +``` + +#### コミットの修正 +```bash +# 最後のコミットメッセージを修正 +git commit --amend -m "corrected commit message" + +# 複数のコミットを整理（インタラクティブリベース） +git rebase -i HEAD~3 +``` + +--- + +## 4. タグ・リリース管理 + +### 🏷️ タグの作成と管理 + +#### セマンティックバージョニング +```bash +# アノテートタグの作成 +git tag -a v1.0.0 -m "Version 1.0.0 - Initial release" + +# ライトウェイトタグの作成 +git tag v1.0.1 + +# タグをリモートにプッシュ +git push origin v1.0.0 + +# すべてのタグをプッシュ +git push origin --tags +``` + +#### GitHub CLI でのタグ作成 +```bash +# タグ作成とリリース同時作成 +gh release create v1.0.0 --title "Version 1.0.0" --notes "初回リリース" + +# プレリリース作成 +gh release create v1.1.0-beta --prerelease --title "Beta Release" --notes "ベータ版" +``` + +### 📦 リリース管理 + +#### GitHub Releases の活用 +```markdown +1. リポジトリページ → Releases → Create a new release +2. 設定項目： + - Tag version: v1.0.0 + - Release title: Version 1.0.0 - New Features + - Description: リリースノート（変更点、新機能など） + - Attach binaries: ビルド成果物のアップロード + - Pre-release: ベータ版の場合はチェック +``` + +#### 自動リリースノート生成 +```yaml +# .github/release.yml +changelog: + exclude: + labels: + - ignore-for-release + categories: + - title: Breaking Changes 🛠 + labels: + - Semver-Major + - breaking-change + - title: Exciting New Features 🎉 + labels: + - Semver-Minor + - enhancement + - title: Bug Fixes 🐛 + labels: + - Semver-Patch + - bug +``` + +--- + +## 5. リポジトリ設定 + +### ⚙️ 一般設定 + +#### 基本情報の設定 +```markdown +Settings → General: +- Repository name: 名前変更 +- Description: 説明文 +- Website: プロジェクトURL +- Topics: 検索用タグ +- Include in the home page: 個人ページでの表示設定 +``` + +#### 機能の有効/無効 +```markdown +Features: +✅ Wikis: プロジェクトドキュメント +✅ Issues: バグ報告・機能要望 +✅ Sponsorships: スポンサー機能 +✅ Preserve this repository: アーカイブ設定 +✅ Discussions: コミュニティディスカッション + +Pull Requests: +✅ Allow merge commits +✅ Allow squash merging +✅ Allow rebase merging +✅ Always suggest updating pull request branches +✅ Automatically delete head branches +``` + +### 🔐 セキュリティ設定 + +#### セキュリティ機能の有効化 +```markdown +Settings → Security: +✅ Dependency graph: 依存関係の可視化 +✅ Dependabot alerts: 脆弱性アラート +✅ Dependabot security updates: 自動セキュリティアップデート +✅ Dependabot version updates: 依存関係の自動更新 +``` + +--- + +## 6. 外部ツールとの比較 + +### 📊 機能比較表 + +| 機能 | GitHub | GitLab | Bitbucket | SVN | 備考 | +|------|--------|--------|-----------|-----|------| +| リポジトリホスティング | ✅ | ✅ | ✅ | ❌ | GitHubは最大規模 | +| ブランチ管理 | ✅ | ✅ | ✅ | ❌ | SVNはtrunk/branches | +| タグ・リリース | ✅ | ✅ | ✅ | ✅ | GitHubのReleasesが最も充実 | +| Web UI | ✅ | ✅ | ✅ | ❌ | GitHubが最もユーザーフレンドリー | +| CLI ツール | ✅ | ✅ | ❌ | ❌ | GitHub CLIが最も強力 | +| ブランチ保護 | ✅ | ✅ | ✅ | ❌ | セキュリティルールの充実度 | + +### 🔄 移行時のポイント + +#### SVN → Git 移行 +```bash +# SVNリポジトリをGitに変換 +git svn clone http://svn.example.com/project + +# GitHubリポジトリを作成 +gh repo create migrated-project --public + +# コードをプッシュ +git remote add origin https://github.com/username/migrated-project.git +git push -u origin main +``` + +#### 他のGitホスティングサービスからの移行 +```bash +# 既存リポジトリをクローン +git clone --mirror https://gitlab.com/user/old-repo.git + +# GitHubに新しいリポジトリを作成 +gh repo create new-repo --public + +# ミラーをプッシュ +cd old-repo.git +git remote set-url origin https://github.com/user/new-repo.git +git push --mirror +``` + +--- + +## 🎓 実践演習 + +### 演習1: リポジトリ作成から保護設定まで +1. 新しいリポジトリを作成 +2. README、.gitignore、ライセンスを設定 +3. developブランチを作成 +4. main ブランチに保護ルールを設定 + +### 演習2: ブランチ戦略の実践 +1. feature ブランチを作成 +2. 機能を実装してコミット +3. プルリクエストを作成 +4. マージ後のブランチクリーンアップ + +### 演習3: リリース管理 +1. セマンティックバージョンでタグ作成 +2. リリースノートを作成 +3. バイナリファイルの添付 +4. 自動リリースノート設定 + +--- + +## 🔗 関連リソース + +- [GitHub Docs - Repositories](https://docs.github.com/en/repositories) +- [GitHub CLI Manual](https://cli.github.com/manual/) +- [Git Documentation](https://git-scm.com/doc) +- [Semantic Versioning](https://semver.org/) +- [Conventional Commits](https://www.conventionalcommits.org/) + +--- + +## 📝 まとめ + +GitHub リポジトリの基本機能をマスターすることで： + +✅ **効率的なコード管理** - ブランチ戦略によるチーム開発の最適化 +✅ **品質保証** - ブランチ保護とレビュープロセスによる品質維持 +✅ **リリース管理** - タグとリリース機能による体系的なバージョン管理 +✅ **セキュリティ** - 適切な設定による安全なコード管理 + +次は[Issue管理編](02-issues-management.md)で、プロジェクト管理の基礎を学習しましょう。 \ No newline at end of file diff --git a/features/02-issues-management.md b/features/02-issues-management.md new file mode 100644 index 0000000..82e434c --- /dev/null +++ b/features/02-issues-management.md @@ -0,0 +1,593 @@ +# 🎫 GitHub Issues 管理 + +GitHub Issuesを活用したプロジェクト管理とタスク追跡の完全ガイド。外部のプロジェクト管理ツールを使わずに、効率的な開発プロセスを構築する方法を学習します。 + +## 🎯 学習目標 + +- Issuesを使った効果的なタスク管理 +- ラベル・マイルストーン・プロジェクトとの連携 +- テンプレートによる標準化 +- 自動化による効率向上 +- 外部ツール（Jira等）との比較理解 + +## 📚 目次 + +1. [Issues基本操作](#1-issues基本操作) +2. [ラベル管理](#2-ラベル管理) +3. [マイルストーン管理](#3-マイルストーン管理) +4. [Issueテンプレート](#4-issueテンプレート) +5. [プロジェクトとの連携](#5-プロジェクトとの連携) +6. [自動化・効率化](#6-自動化効率化) +7. [外部ツールとの比較](#7-外部ツールとの比較) + +--- + +## 1. Issues基本操作 + +### 📝 Issue作成 + +#### Web UIでの作成 +```markdown +1. リポジトリページ → Issues → New issue +2. 入力項目： + - Title: 簡潔で分かりやすいタイトル + - Comment: 詳細な説明（Markdown記法使用可能） + - Assignees: 担当者の指定 + - Labels: 分類用ラベル + - Projects: 関連プロジェクト + - Milestone: 対象マイルストーン +``` + +#### GitHub CLI での作成 +```bash +# 基本的なIssue作成 +gh issue create --title "バグ修正: ログイン機能が動作しない" --body "ログインボタンをクリックしても反応がない" + +# テンプレートを使用してIssue作成 +gh issue create --template bug_report.md + +# ラベルと担当者を指定 +gh issue create --title "新機能: ユーザープロフィール" --label "enhancement,frontend" --assignee username +``` + +### 🔍 Issue検索・フィルタリング + +#### 高度な検索クエリ +```bash +# オープンなIssuesのみ +is:open is:issue + +# 自分が担当のIssues +is:issue assignee:@me + +# 特定のラベルが付いたIssues +is:issue label:bug + +# 複数条件の組み合わせ +is:issue is:open label:enhancement assignee:username + +# 作成日でフィルタ +is:issue created:>2024-01-01 + +# コメント数でフィルタ +is:issue comments:>5 + +# マイルストーンでフィルタ +is:issue milestone:"Version 2.0" +``` + +#### GitHub CLI での検索 +```bash +# オープンなバグIssuesを表示 +gh issue list --label bug --state open + +# 自分が担当のIssuesを表示 +gh issue list --assignee @me + +# JSONで出力（スクリプト処理用） +gh issue list --json number,title,labels,assignees +``` + +### 💬 Issue管理 + +#### コメントとやり取り +```markdown +# メンション機能 +@username こちらの件、確認をお願いします。 + +# 他のIssue参照 +この問題は #123 と関連があります。 + +# コミット参照 +この修正は a1b2c3d で対応済みです。 + +# PR参照 +修正は #45 で対応中です。 +``` + +#### Issue状態管理 +```bash +# CLI でIssueをクローズ +gh issue close 123 --comment "修正が完了しました" + +# 理由を指定してクローズ +gh issue close 123 --reason "completed" # または "not planned" + +# Issueを再オープン +gh issue reopen 123 + +# 担当者を変更 +gh issue edit 123 --add-assignee newuser --remove-assignee olduser +``` + +--- + +## 2. ラベル管理 + +### 🏷️ 効果的なラベル体系 + +#### 推奨ラベル構成 +```yaml +# 種類別（Type） +- bug: バグ報告 +- enhancement: 新機能・改善 +- documentation: ドキュメント関連 +- question: 質問・サポート +- duplicate: 重複Issue + +# 優先度別（Priority） +- priority:high: 緊急度高 +- priority:medium: 通常優先度 +- priority:low: 低優先度 + +# 状態別（Status） +- status:ready: 作業可能 +- status:in-progress: 作業中 +- status:blocked: ブロックされている +- status:review: レビュー待ち + +# 領域別（Area） +- area:frontend: フロントエンド +- area:backend: バックエンド +- area:api: API関連 +- area:ui-ux: UI/UX +- area:performance: パフォーマンス +- area:security: セキュリティ + +# サイズ別（Effort） +- size:small: 小規模（1-2日） +- size:medium: 中規模（3-5日） +- size:large: 大規模（1週間以上） +``` + +#### ラベル作成と管理 +```bash +# GitHub CLI でラベル作成 +gh label create "priority:high" --color "FF0000" --description "緊急度の高いタスク" + +# 既存ラベルの編集 +gh label edit "bug" --color "FF6B6B" --description "バグ報告" + +# ラベル一覧表示 +gh label list + +# ラベル削除 +gh label delete "outdated-label" +``` + +### 🎨 ラベルの色分けとベストプラクティス + +#### 色分けの推奨方式 +```markdown +🔴 高優先度・緊急: #FF0000 (赤) +🟠 中優先度: #FFA500 (オレンジ) +🟡 低優先度: #FFFF00 (黄) +🟢 完了・承認: #00FF00 (緑) +🔵 情報・質問: #0000FF (青) +🟣 進行中: #800080 (紫) +⚫ ブロック・問題: #000000 (黒) +``` + +--- + +## 3. マイルストーン管理 + +### 🎯 マイルストーンの設計 + +#### 効果的なマイルストーン例 +```markdown +# バージョンベース +- v1.0.0 - 初回リリース (2024-03-01) +- v1.1.0 - 機能追加 (2024-04-15) +- v2.0.0 - メジャーアップデート (2024-06-30) + +# 機能ベース +- User Authentication System +- Payment Integration +- Mobile App Support + +# 時期ベース +- Q1 2024 Goals +- Summer Release +- Year-end Cleanup +``` + +#### マイルストーン作成と管理 +```bash +# マイルストーン作成 +gh issue create-milestone "v1.0.0" --description "初回リリース" --due-date "2024-03-01" + +# マイルストーン一覧 +gh issue list-milestones + +# Issueをマイルストーンに割り当て +gh issue edit 123 --milestone "v1.0.0" +``` + +### 📊 進捗管理 + +#### マイルストーン進捗の可視化 +```markdown +# マイルストーンページで確認できる情報： +- 全体の進捗率（パーセンテージ） +- オープン・クローズされたIssue数 +- 期限までの残り時間 +- 各Issueの状態 +``` + +--- + +## 4. Issueテンプレート + +### 📄 テンプレート作成 + +#### バグ報告テンプレート +```yaml +# .github/ISSUE_TEMPLATE/bug_report.yml +name: 🐛 バグ報告 +description: バグを報告するためのテンプレート +title: "[BUG] " +labels: ["bug", "needs-triage"] +assignees: + - maintainer-username +body: + - type: markdown + attributes: + value: | + バグを報告いただき、ありがとうございます。以下の情報を詳しく記入してください。 + + - type: textarea + id: bug-description + attributes: + label: 🐛 バグの説明 + description: バグの詳細な説明を記入してください + placeholder: 何が起こっているか、期待される動作との違いを説明 + validations: + required: true + + - type: textarea + id: reproduction-steps + attributes: + label: 🔄 再現手順 + description: バグを再現する手順を記入してください + placeholder: | + 1. ○○のページに移動 + 2. ○○をクリック + 3. ○○を入力 + 4. エラーが発生 + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: ✅ 期待される動作 + description: 本来はどのような動作を期待していましたか？ + validations: + required: true + + - type: textarea + id: environment + attributes: + label: 🖥️ 環境情報 + description: 環境に関する情報 + placeholder: | + - OS: [例: Windows 10, macOS 13.0, Ubuntu 20.04] + - ブラウザ: [例: Chrome 108, Firefox 107, Safari 16] + - バージョン: [例: v1.2.3] + validations: + required: true + + - type: textarea + id: additional-context + attributes: + label: 📋 追加情報 + description: スクリーンショット、ログ、その他関連情報があれば記入してください + placeholder: エラーメッセージ、スクリーンショットなど +``` + +#### 機能要求テンプレート +```yaml +# .github/ISSUE_TEMPLATE/feature_request.yml +name: ✨ 機能要求 +description: 新機能や改善の要求 +title: "[FEATURE] " +labels: ["enhancement", "needs-discussion"] +body: + - type: markdown + attributes: + value: | + 新機能の提案をありがとうございます！ + + - type: textarea + id: problem-description + attributes: + label: 🎯 解決したい問題 + description: この機能によってどのような問題を解決したいですか？ + placeholder: 現在困っていることや、改善したい点を説明してください + validations: + required: true + + - type: textarea + id: proposed-solution + attributes: + label: 💡 提案する解決策 + description: どのような機能や改善を提案しますか？ + placeholder: 具体的な機能の説明や実装案があれば記入してください + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: 🔄 代替案 + description: 他に考えられる解決策があれば記入してください + placeholder: 別のアプローチや既存の回避策など + + - type: textarea + id: additional-context + attributes: + label: 📋 追加情報 + description: 参考資料、モックアップ、外部リンクなど + placeholder: 関連するリンクやファイルがあれば記入してください +``` + +### ⚙️ テンプレート設定 + +#### 設定ファイルの作成 +```yaml +# .github/ISSUE_TEMPLATE/config.yml +blank_issues_enabled: false +contact_links: + - name: 💬 Q&A ディスカッション + url: https://github.com/username/repo/discussions + about: 質問がある場合はこちらをご利用ください + - name: 📖 ドキュメント + url: https://docs.example.com + about: 使い方やAPIドキュメントはこちら +``` + +--- + +## 5. プロジェクトとの連携 + +### 📋 GitHub Projects 連携 + +#### Issueの自動プロジェクト追加 +```yaml +# .github/workflows/add-to-project.yml +name: Add Issue to Project +on: + issues: + types: [opened] + +jobs: + add-to-project: + runs-on: ubuntu-latest + steps: + - uses: actions/add-to-project@v0.4.0 + with: + project-url: https://github.com/users/username/projects/1 + github-token: ${{ secrets.ADD_TO_PROJECT_TOKEN }} +``` + +#### ラベルベースの自動ワークフロー +```yaml +# ラベルに応じて列を移動 +name: Move Issue Based on Label +on: + issues: + types: [labeled] + +jobs: + move-issue: + runs-on: ubuntu-latest + if: github.event.label.name == 'in-progress' + steps: + - name: Move to In Progress + uses: leonsteinhaeuser/project-beta-automations@v2.0.1 + with: + gh_token: ${{ secrets.GITHUB_TOKEN }} + user: username + project_id: 1 + resource_node_id: ${{ github.event.issue.node_id }} + status_value: "In Progress" +``` + +--- + +## 6. 自動化・効率化 + +### 🤖 GitHub Actions による自動化 + +#### Issue自動ラベリング +```yaml +# .github/workflows/label-issues.yml +name: Auto Label Issues +on: + issues: + types: [opened] + +jobs: + label: + runs-on: ubuntu-latest + steps: + - uses: actions/labeler@v4 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + configuration-path: .github/labeler.yml +``` + +```yaml +# .github/labeler.yml +"area:frontend": + - "**/*.js" + - "**/*.vue" + - "**/*.css" + +"area:backend": + - "**/*.py" + - "**/*.go" + - "**/*.java" + +"documentation": + - "**/*.md" + - "docs/**/*" +``` + +#### 古いIssueの自動クローズ +```yaml +# .github/workflows/stale-issues.yml +name: Close Stale Issues +on: + schedule: + - cron: '0 0 * * 0' # 毎週日曜日 + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v8 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + stale-issue-message: | + このIssueは60日間活動がありません。 + 7日以内に活動がない場合、自動的にクローズされます。 + close-issue-message: | + このIssueは非アクティブのため自動的にクローズされました。 + days-before-stale: 60 + days-before-close: 7 +``` + +### 📊 Issue分析・レポート + +#### CLI による統計取得 +```bash +# Issue統計を取得するスクリプト +#!/bin/bash + +echo "=== Issue Statistics ===" +echo "Total Issues: $(gh issue list --limit 1000 --json number | jq length)" +echo "Open Issues: $(gh issue list --state open --limit 1000 --json number | jq length)" +echo "Closed Issues: $(gh issue list --state closed --limit 1000 --json number | jq length)" + +echo -e "\n=== Issues by Label ===" +gh issue list --limit 1000 --json labels | jq -r '.[].labels[].name' | sort | uniq -c | sort -nr + +echo -e "\n=== Issues by Assignee ===" +gh issue list --limit 1000 --json assignees | jq -r '.[].assignees[].login' | sort | uniq -c | sort -nr +``` + +--- + +## 7. 外部ツールとの比較 + +### 📊 機能比較表 + +| 機能 | GitHub Issues | Jira | Trello | Linear | 備考 | +|------|---------------|------|--------|--------|------| +| 基本的なIssue管理 | ✅ | ✅ | ✅ | ✅ | 全て対応 | +| カスタムフィールド | ❌ | ✅ | ❌ | ✅ | GitHubはラベルで代用 | +| ワークフロー管理 | ⚠️ | ✅ | ⚠️ | ✅ | GitHubはActionsで実現 | +| 時間トラッキング | ❌ | ✅ | ⚠️ | ✅ | 外部サービス連携が必要 | +| レポート機能 | ⚠️ | ✅ | ❌ | ✅ | APIやInsightsを活用 | +| マイルストーン | ✅ | ✅ | ❌ | ✅ | GitHubのマイルストーン機能 | +| サブタスク | ❌ | ✅ | ✅ | ✅ | GitHubはタスクリストで代用 | +| コード連携 | ✅ | ⚠️ | ❌ | ⚠️ | GitHubが最も強力 | +| コスト | 無料〜 | 有料 | 無料〜 | 有料 | GitHubがコスト効率良い | + +### 🔄 Jira からの移行 + +#### 移行チェックリスト +```markdown +✅ Issue種別 → ラベルでの分類方法決定 +✅ ワークフロー → GitHub Projects V2 での再現 +✅ カスタムフィールド → ラベルやマイルストーンでの代替 +✅ レポート → GitHub API + スクリプトでの実現 +✅ 時間管理 → 外部サービス連携の検討 +✅ 権限管理 → リポジトリレベルでの設定調整 +``` + +#### 移行スクリプト例 +```python +# jira_to_github.py +import requests +import json + +def migrate_issues(jira_url, github_repo, token): + # Jira API からIssue取得 + jira_issues = fetch_jira_issues(jira_url) + + for issue in jira_issues: + # GitHub Issue 形式に変換 + github_issue = { + 'title': issue['fields']['summary'], + 'body': convert_description(issue['fields']['description']), + 'labels': map_jira_labels(issue['fields']['labels']) + } + + # GitHub API でIssue作成 + create_github_issue(github_repo, github_issue, token) +``` + +--- + +## 🎓 実践演習 + +### 演習1: Issue管理システム構築 +1. バグ報告と機能要求のテンプレートを作成 +2. 体系的なラベル分類を設計 +3. マイルストーンを設定してIssueを分類 + +### 演習2: 自動化ワークフロー作成 +1. 新しいIssueの自動ラベリング設定 +2. 古いIssueの自動クローズ設定 +3. プロジェクトボードとの連携設定 + +### 演習3: レポート・分析 +1. Issue統計取得スクリプトの作成 +2. 進捗レポートの自動生成 +3. チームパフォーマンス分析 + +--- + +## 🔗 関連リソース + +- [GitHub Docs - Issues](https://docs.github.com/en/issues) +- [GitHub Issues Templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests) +- [GitHub Projects Documentation](https://docs.github.com/en/issues/planning-and-tracking-with-projects) +- [GitHub CLI Issues](https://cli.github.com/manual/gh_issue) + +--- + +## 📝 まとめ + +GitHub Issues を効果的に活用することで： + +✅ **統一されたタスク管理** - 外部ツール不要でプロジェクト管理 +✅ **コードとの密接な連携** - コミット・PRとのシームレスな連携 +✅ **自動化による効率化** - GitHub Actions による作業自動化 +✅ **コスト削減** - 有料ツールからの移行によるコスト最適化 +✅ **チーム協調** - 透明性の高い情報共有とコミュニケーション + +次は[Pull Request編](03-pull-requests.md)で、コードレビューとマージプロセスを学習しましょう。 \ No newline at end of file diff --git a/index.md b/index.md new file mode 100644 index 0000000..ef8f2e2 --- /dev/null +++ b/index.md @@ -0,0 +1,261 @@ +--- +layout: home +title: "GitHub完全活用ガイド" +description: "外部ツールに依存せず、GitHub一つで開発業務を完結させるための網羅的解説書" +--- + +# 🚀 GitHub完全活用ガイド + +> **GitHub機能を網羅的に理解し、開発プロセスを最適化するための実践的解説書** + +
+

🎯 このサイトで学べること

+
+
+

🔧 実務で使える設定

+

すぐに実装できる設定例とベストプラクティス

+
+
+

💰 コスト削減

+

外部ツール費用を年間37%削減する方法

+
+
+

📈 効率化

+

開発フローを2倍高速化するワークフロー

+
+
+

🛡️ セキュリティ

+

企業レベルのセキュリティを無料で実現

+
+
+
+ +## 📚 メインコンテンツ + +### 🎯 [完全活用ガイド](GITHUB_COMPLETE_GUIDE.html) +**GitHub機能の全体像から実装まで網羅した決定版ガイド** +- 全10章で構成された包括的な解説 +- 実際のコード例とスクリーンショット付き +- 段階的な実装計画とチェックリスト + +### 📖 機能別詳細ガイド + +
+ +

📁 リポジトリ基礎

+

作成から保護設定まで基本操作をマスター

+ + + +

🎫 Issues管理

+

Jiraを完全代替するタスク管理システム

+ + + +

🔄 Pull Request

+

効率的なコードレビューフロー（準備中）

+ + + +

📋 GitHub Projects

+

アジャイル開発のためのプロジェクト管理（準備中）

+ +
+ +## 🎓 学習の進め方 + +### 初心者の方 +1. **[リポジトリ基礎](features/01-repository-basics.html)** で基本操作を習得 +2. **[Issues管理](features/02-issues-management.html)** でタスク管理を体験 +3. **[完全ガイド](GITHUB_COMPLETE_GUIDE.html)** で全体像を把握 + +### 経験者の方 +1. **[完全ガイド](GITHUB_COMPLETE_GUIDE.html)** で新機能をチェック +2. **外部ツール代替戦略** で移行計画を立案 +3. **実務ケーススタディ** で最適な導入方法を選択 + +### チームリーダーの方 +1. **コスト分析** で導入効果を試算 +2. **段階的移行計画** でリスクを最小化 +3. **実装チェックリスト** で確実な導入を実現 + +## 🎉 導入効果の実例 + +
+
+

37%

+

年間コスト削減

+
+
+

2倍

+

開発速度向上

+
+
+

50%

+

障害対応時間短縮

+
+
+

85%

+

Issue解決率向上

+
+
+ +## 🔗 クイックスタート + +すぐに始めたい方は、以下の手順で進めてください： + +```bash +# 1. 新しいリポジトリを作成 +gh repo create my-project --public + +# 2. 基本設定を適用 +git clone https://github.com/username/my-project +cd my-project + +# 3. Issue管理を開始 +gh issue create --title "プロジェクト初期設定" --body "GitHub機能の設定を開始" +``` + +詳細な手順は **[完全ガイド](GITHUB_COMPLETE_GUIDE.html)** をご覧ください。 + +## 📞 サポート・質問 + +- **GitHub Issues**: バグ報告・機能要望 +- **GitHub Discussions**: 質問・アイデア共有 +- **GitHub Wiki**: FAQ・トラブルシューティング + +--- + +
+

🚀 今すぐ始めよう！

+

GitHub一つで完結する開発環境を構築し、
生産性とコスト効率を劇的に改善しましょう。

+ 完全ガイドを読む +
+ + \ No newline at end of file