次の方法で共有

Git および GitHub の Microsoft Learn ドキュメントの基礎

  • [アーティクル]

概要

Microsoft Learnドキュメントの共同作成者として、複数のツールとプロセスを操作します。 同じプロジェクトで他の共同作成者と並行して作業を行います。まったく同じコンテンツで同時に作業を行う場合もあります。 これらのすべては Git と GitHub ソフトウェアによって実現します。

Git はオープン ソースのバージョン管理システムです。 リポジトリ に存在するファイルの分散型バージョン管理 により、この種のプロジェクト コラボレーションを容易にします。 要するに、Git を利用することで、特定のリポジトリを対象に複数の共同作成者によって長期間にわたって行われる一連の作業を統合できます。

GitHub は、Microsoft Learn コンテンツの格納に使用しているような Git リポジトリの、Web ベースのホスティング サービスです。 GitHub は任意のプロジェクトのメイン リポジトリをホストします。共同作成者はこのメイン リポジトリから独自の作業用のコピーを作成できます

この記事では、Microsoft Learn ワークフローの一部である主要な用語を定義します。 また、Git リポジトリと GitHub リポジトリの概要、および Microsoft 技術ドキュメントのコンテンツの構成方法についても説明します。

Branch

ブランチは作業ストリームを分離します (通常はバージョンと呼ばれる)。 共同作成の範囲は必ず特定のブランチに設定されます。

関連性のある変更内容を特定のブランチに分離することにより、それらの変更内容を個別に管理して導入できます。 実際に、実施する作業の種類によっては、独自のリポジトリ内に複数の作業ブランチが存在するようになることがよくあります。 それぞれに異なるプロジェクトの作業が、複数のブランチで同時に進行するのは珍しいことではありません。

すべてのリポジトリには、既定のブランチにまだ統合されていない既定のブランチ (通常は "メイン" という) と 1 つ以上の進行中のブランチ (作業ブランチと呼ぶ) が含まれています。 既定のブランチは、プロジェクトの現在のバージョンおよび "信頼できる唯一の情報源" となります。 これは、そのリポジトリ内の他のすべてのブランチの作成元となる親です。

論理的に関連性のある新しい複数の変更内容を導入するときはいつでも、独自の変更内容を管理するための "作業ブランチ" を作成することがベスト プラクティスです。 既定のブランチを直接変更することはお勧めしません。

フォーク

この用語は通常、メイン GitHub リポジトリのコピーを指すときに、名詞として使用されます。 実際には、フォークは別のリポジトリです。 ただし、GitHub でメイン/親リポジトリへの接続が維持される点で、これは特殊です。 この用語は、"最初にリポジトリをフォークする必要があります" のように、動詞として使用されることもあります。

Git

集中型バージョン管理システム (Team Foundation Server、SharePoint、Visual SourceSafe など) を使い慣れている場合、Git に分散型モデルをサポートする固有の共同作成ワークフローと用語があることに気付かれるでしょう。 たとえば、通常はチェックアウト/チェックイン操作と関連するファイル ロックはありません。 その代わりに、Git では最小レベルの変更でさえも考慮されており、ファイルはバイト単位で比較されます。

また、Git では階層化された構造を使用して、プロジェクトのコンテンツを格納および管理します。

  • "リポジトリ" : これは"リポ" とも呼ばれる最上位の記憶域単位です。 リポジトリには 1 つまたは複数のブランチが含まれます。
  • "ブランチ": プロジェクトのコンテンツ セットを構成するファイルとフォルダーを含む記憶域単位です。 ブランチの詳細については、この記事の「ブランチ」セクションを参照してください。

共同作成者は以下の方法で Git と対話して、ローカル レベルと GitHub レベルの両方でリポジトリを更新および処理します。

  • ローカルでは、ローカル リポジトリの管理や GitHub リポジトリとの通信のための Git のコマンドをサポートするツール (Git Bash コンソールなど) を利用します。
  • Git を統合する www.github.com を利用して、メイン リポジトリに戻される共同作成の整合を管理します。

GitHub

Note

ドキュメントのガイダンスは GitHub の使用を前提としていますが、チームによっては Visual Studio Team Services を利用して Git リポジトリをホスティングします。 Visual Studio Team Explorer クライアントでは、コマンド ラインで Git コマンドを使用する代わりに、GUI を利用して Team Services リポジトリと対話できます。
また、後述のガイドラインの多くは、GitHub で Azure サービスのコンテンツをホストしてきた長年の経験からのベスト プラクティスとして開発されました。 一部の Microsoft Learn リポジトリでは必須である可能性があります。

すべてのワークフローは任意のドキュメント プロジェクトのメイン リポジトリが格納されている GitHub レベルで始まり、GitHub レベルで終わります。 共同作成者が自分で使用するために作成するコピーは、複数のコンピューターに配信されます。 これらのコピーは最終的に、プロジェクトのメイン GitHub リポジトリに戻されて整合されます。

ディレクトリの構成

プロジェクトの既定のブランチは、プロジェクト コンテンツの最新バージョンとして機能します。 既定のブランチ (およびそこから作成されたブランチ) のコンテンツは、対応する Microsoft Learn ページの記事の構成と大まかに一致します。 同じような記事 (サービスなど)、メディア コンテンツ (イメージ ファイルなど)、および "インクルード" ファイル (コンテンツの再利用を可能にする) を分離するために、サブディレクトリが使用されます。

Articles サブディレクトリ

通常、メイン articles ディレクトリはリポジトリのルートの直下にあります。 articles ディレクトリには、サブディレクトリのセットが含まれています。サブディレクトリ内の記事は、拡張子 .md を使用する Markdown ファイルとしてフォーマットされます。 複数のサービスをサポートするリポジトリでは、共通の /articles サブディレクトリが使用されることがあります。たとえば、Azure-Docs リポジトリです。 サービス固有の名前が使用される場合もあります。たとえば、IntuneDocs リポジトリでは /IntuneDocs が使用されます。

このディレクトリのルートには、サービスまたは製品全体に関する記事全般があります。 通常ではその他に、機能/サービスまたは共通のシナリオに対応する一連のサブディレクトリがあります。 たとえば、Azure の "仮想マシン" に関する記事はサブディレクトリ /virtual-machines にあり、Intune の "理解と探索" に関する記事はサブディレクトリ /understand-explore にあります。

メディアのサブディレクトリ

各記事のディレクトリには、対応するメディア ファイルの /media サブディレクトリが含まれます。 メディア ファイルには、イメージ参照がある記事で使用されるイメージが含まれます。

インクルード サブディレクトリ

2 つ以上の記事で共有される再利用可能なコンテンツがある場合は常に、メイン articles ディレクトリの直下にあるサブディレクトリ /includes に配置されます。 インクルード ファイルを使用する Markdown ファイルでは、インクルード ファイルが参照される必要がある場所に、対応する "include" Markdown の拡張機能が配置されます。

追加のガイダンスについては、Markdown のインクルードのリファレンスの記事を参照してください。

Markdown ファイルのテンプレート

便宜上、各リポジトリのルート ディレクトリには通常、template.md という名前の Markdown テンプレート ファイルが含まれます。 新しい記事を作成してリポジトリに送信する必要がある場合は、このテンプレート ファイルを "開始ファイル" として使用できます。 ファイルには、次のものが含まれます。

  • ファイルの冒頭にあるメタデータ ヘッダー。3 つのハイフンで構成される 2 本の線で区切られます。 記事に関連する情報の追跡に使用される各種タグが含まれます。 記事のメタデータでは、作成者の属性、共同作成者の属性、階層リンク、および記事の説明など、特定の機能を使用できます。 これには、Microsoft がコンテンツのパフォーマンス評価に使用する SEO の最適化やレポート プロセスも含まれます。 このように、メタデータは重要な要素です。
  • メタデータのさまざまなタグや値を説明するメタデータ セクション。 メタデータ セクションで使用する値がわからない場合、空白のままにするか、先頭にハッシュタグ (#) を付けたコメントを残すことができます。これらはリポジトリの pull request レビュー担当者によってレビュー/完了されます。
  • 記事の要素の書式を設定するさまざまな Markdown の使用例。
  • Markdown 拡張機能の使用に関する説明全般。これはさまざまな種類のアラートに使用できます。
  • iframe を使用したビデオ埋め込みの例。
  • Microsoft 技術ドキュメント拡張機能の使用に関する説明全般。これはボタンやセレクターなどの特殊なコントロールに使用できます。

元のドメイン

この用語は、ローカル リポジトリとその複製元リポジトリとの間の接続に割り当てられた名前です。 Microsoft Learn ワークフローでは、origin はフォークへの接続を表します。 この用語は、"忘れずに変更を origin にプッシュしてください" のように、元のリポジトリ自体のモニカーとして使用されることもあります。

プルリクエスト

pull request (PR) は、コンテンツ所有者が変更を公式ソースにプルするためのリクエストです。 PR は、作業ブランチの変更内容 (コミットとも呼ばれる) をプルし、別のブランチにマージするように求めることで、GitHub のコラボレーション モデルを可能にします。 ほとんどの場合、このもう 1 つのブランチは、メイン リポジトリの既定のブランチです。

PR は、変更内容が既定のブランチにマージされる前に潜在的な問題や疑問を解消するために、Microsoft Learn の検証プロセスと PR レビュー担当者からのフィードバックを共同作成者に提供するメカニズムとしても機能します。

Remote

リモートは、リモート リポジトリへの名前付きの接続です ("オリジン" リモートや "アップストリーム" リモートなど)。 Git では、これは別のコンピューターでホストされているリポジトリへの参照に使用されるため、"リモート" と呼ばれます。 Microsoft Learn ワークフローでは、リモートは常に GitHub リポジトリです。

上流

オリジン リポジトリと同様に、アップストリームは、別のリポジトリへの名前付きの接続のことです。 Microsoft Learn ワークフローでは、アップストリームは、ローカル リポジトリと、フォーク作成時に基となったメイン リポジトリとの間の接続を表します。 この用語は、"忘れずにアップストリームから最新の変更内容をプルしてください" のように、アップストリーム リポジトリ自体のモニカーとして使用されることもあります。

詳細情報

Git または GitHub についてまだよく知らない場合は、学習、生産性の向上、質問への回答に以下のリソースが役立つ場合があります。

Git ソース管理リソース

GitHub リソース

よく寄せられる質問

Git とは？

Git は、多くのユーザーが一緒にコンピューター Codeで作業するときの変更点をトラッキングするのに役立ちます。 CodeのTIME マシンのようなものなので、何が変更されたかを確認し、必要に応じて戻ることができます。

Gitを使用する理由とは？

チームワークに最適です。 Git を使用すると、多くのユーザーが互いの作業を混乱させることなく、同じプロジェクトで簡単に作業できます。 また、簡単に間違いをフィックスするのに役立ちます。

Gitはどのように機能しますか?

Git には、プロジェクトのCodeのすべてのバージョンが格納されます。 変更を加えると、Git は何が異なるかを (スナップショットのように) 画像で取得します。 問題なく、異なるバージョンを同時に作成できます。

Git のブランチとは？

ブランチは、プロジェクト内の異なるパスに似ています。 ユーザーは、メイン プロジェクトを変更することなく、新しい作業を行います。 後で、これらの変更点をメイン プロジェクトに戻すことができます。

Git でのコミットとは？

コミットは保存ポイントのようなものです。 これは、行った変更点をレコードする方法です。 各コミットには、一意の ID と、変更された内容に関するメモがあります。

GitHub とは

GitHub は、Git プロジェクトを格納できる Web サイトです。 これは、他のユーザーとCodeを共有して連携するための大きなハブのようなものです。 また、誰が何を変更したかをトラックするのにも役立ちます。

GitHub と Git の違いとは？

Git は変更点をトラッキングするためのツールですが、GitHub はプロジェクトを格納して共同作業を行う場所です。 GitHub では Git を使用してマジックを行います。

GitHub は無料ですか?

はい。プロジェクトの場合、誰もが見ることができます。 ただし、個人用 プロジェクト (自分とチームのみ) の場合は、支払いが必要になる場合があります。 追加機能を備えたさまざまなプランを提供しています。

GitHubのpull request とは？

pull requestは、変更点をメイン プロジェクトに配置するように求めるのと同じです。 ユーザーは、追加する前に変更点をレビューして話し合うことができます。

GitHub の安全性はどのくらいですか?

GitHub はセキュリティを十分に管理します。 特別なCodeとルールを使用して、適切なユーザーのみがCodeにアクセスして変更できるようにします。 2 要素認証などの追加のセキュリティレイヤーを追加して、安全性を高めることもできます。