Skip to content

README_github.md

Latest commit

 

History

History
103 lines (86 loc) · 5.29 KB

README_github.md

File metadata and controls

103 lines (86 loc) · 5.29 KB

GitHub 運用ガイド（VS Code中心）

このドキュメントは、コマンドではなく VS Code のソース管理機能を中心に、ドキュメント変更の手順を説明します。対象は「Docs as Code」プロジェクトです。

必須拡張

  • GitHub Pull Requests and Issues（Microsoft）
  • GitLens（任意）

役割の前提

  • 執筆者（作る人）
  • レビュアー（確認・承認する人）

1. ブランチを切って作業する

  1. VS Code 左の「ソース管理」→「ブランチ」→「新しいブランチの作成」
  • ブランチ名例: docs/feature-章2追加 docs/fix-表現修正
  • 既定のベースは main（または develop）を選択
  1. 右下の通知で「公開（Publish）」を実行し、リモートにもブランチを作成

2. 変更してコミットする

  1. 該当の .md を編集（cover.md, chapXX/index.md 等）
  2. ソース管理ビューで変更を確認
  3. コミットメッセージを入力して「コミット」
  • 推奨（Conventional Commits準拠・ドキュメント向け）:
    • docs: 章2 に 2.3 節を追加
    • docs: 図のキャプションを修正
    • chore: build スタイルを微調整
  • 複数の変更を分けたい場合は、小さく頻繁にコミット
  1. 「同期（Sync）」または「プッシュ（Push）」

3. プルリクエスト（PR）を作成

  1. 左の GitHub アイコン（またはステータスバー）から「Create Pull Request」
  2. 対象ブランチ main（または運用の基準ブランチ）に向けてPRを作成
  3. タイトルと説明を記入
  • タイトル例: docs: 2章の追記（2.1〜2.3）
  • 説明には、概要/背景/変更範囲/レビューポイントを簡潔に
  1. レビュアーとラベルを設定
  2. Issue と関連付け（例）: 説明に Closes #123 / Refs #123 を記載

4. レビュー対応

  • レビュアーからのコメントは VS Code で「GitHub」ビューから一覧可能
  • 指摘箇所を修正 → 再コミット＆プッシュ → PRに自動反映
  • 追加の変更依頼が来たら同ブランチで続けてコミット

5. マージ（取り込み）

  • 承認後、PR画面から「Squash and merge」または「Merge」
  • Docsでは履歴を簡潔にするため Squash and merge 推奨
  • マージ後はローカルの作業ブランチを削除してOK（VS Codeに削除ボタンあり）

6. バージョン管理とタグ

  • リリース区切りのタイミングでタグを付与
  • 命名例: v0.0.1（初回セットアップ＋GitHub運用ガイド追加）
  • VS Codeの「ソース管理 > タグ」または GitHubの「Releases」から作成

7. Issue の使い方（最低限）

  • ドキュメント作業のTODOはIssue化して透明性を上げる
  • テンプレ（例）:
    • 概要
    • 背景/目的
    • 変更対象ファイル
    • 受入基準（チェックリスト）
  • コミット/PR本文に Closes #<番号> を入れると、マージ時に自動クローズ

8. Conventional Commits（ドキュメント向け抜粋）

  • docs: ドキュメント本文の変更
  • chore: ビルド/ツール/設定の変更（出力物に影響がない）
  • feat: 目立つ新機能や大きな構成変更（テンプレ拡張など）
  • fix: 不具合修正（リンク切れ、番号ズレなど）
  • 例:
    • docs: 1章の図番号を見直し
    • docs: 目次の章番号フォーマットを更新
    • fix: 画像パスの誤りを修正
    • chore: vscode 推奨拡張を追加

9. よくある質問

  • PRを作るタイミングは？ → 1日のまとまりか、レビューしてほしい単位で。小さめ歓迎。
  • 画像ファイルはどこに置く？ → 各節の images/<節名>/。
  • PDFの生成は？ → PRでもローカルでも「Build PDF」でOK。必要なら成果物をPRに添付。

このガイドに沿えば、コマンドを使わずに VS Code だけでブランチ〜PR〜マージまで完結できます。

10. バージョニングの基本方針（ドキュメント向け）

  • 付与単位は Git タグ（例: v0.0.1）。区切りの良い変更ごとに付けます。
  • 目安（SemVerをドキュメント用に簡略化）
    • 破壊的/大幅な構成変更: MAJOR を上げる（例: 1.x → 2.0.0）
    • 章・節の追加などの機能的拡張: MINOR を上げる（例: 1.2 → 1.3.0）
    • 誤字修正/図差し替え/目次調整など微修正: PATCH を上げる（例: 1.2.3 → 1.2.4）
  • 運用例
    1. Issue 作成（目的/範囲/受入基準）
    2. ブランチ作成 → 作業 → PR 作成（説明に Closes #<番号>）
    3. レビュー承認 → main にマージ
    4. 区切りの良い状態でタグ vX.Y.Z を作成（Releases にメモ）

Issue / PR / タグの関係（基本）

  • Issue は「やる理由と成果物の定義」
  • PR は「Issue を満たすための変更の集合」
  • タグは「レビューを完了した成果物のスナップショット」
  • 例: Issue #23 → PR #45（Closes #23）→ マージ → タグ v0.1.0

Conventional Commits（再掲）

  • docs: ドキュメント本文、feat: 大きな拡張、fix: 不具合、chore: 設定類
  • リリースノート化をしやすくするため、PRタイトル/説明にも同趣旨を反映