Microsoft Learn の投稿の基礎

  • 6 分

投稿プロセスを理解して完了するのに役立つ知っておくべき用語がいくつかあります。 内部で起こっていることすべてを知る必要はありませんが、投稿のしくみの概要は、プロセスがなぜそのように動作しているのかを理解するのに役立ちます。

Microsoft Learn と GitHub の基礎

Microsoft Learn には、さまざまな共同作成者が保存して定期的にアクセスする必要がある、何千もの記事、トレーニング モジュール、Web ページなどが含まれています。 Microsoft Learn は、GitHub を使用してこのコンテンツの多くを保存しています。 GitHub は、分散バージョン管理システムである Git を使用してプロジェクトを保存し、さまざまなプロジェクト目標とタイムラインを持つ複数の関係者間のコラボレーションを促進するプラットフォームです。 Git および GitHub ソフトウェアを使用すると、同じプロジェクトの他の共同作成者と、原理的にはまったく同じコンテンツに対して、同時に、意図せず他者の作業に干渉することなく、並行して作業できます。

コンテンツは、GitHub でホストされる Git "リポジトリ" (repo) 内のファイルに保存されます。 リポジトリは、プロジェクトのファイルとファイル リビジョン履歴を含む保管単位です。 リポジトリはパブリックまたはプライベートにすることができ、Microsoft Learn は両方の組み合わせで構成されています。 GitHub アカウントを設定すると、誰でもパブリック リポジトリに投稿できます。 プライベート リポジトリは、Microsoft の従業員である、または特別なアクセス許可が与えられている共同作成者のみが使用できます。

GitHub リポジトリに保存されている Microsoft Learn コンテンツを編集する

どのプロジェクトでも、GitHub はメイン リポジトリと何らかの "フォーク" をホストしています。 フォークは、共同作成者が独自の作業のために作成するメイン リポジトリのコピーです。 フォークは、公開されたコンテンツを保護する GitHub の方法の 1 つです。 GitHub では、メイン リポジトリの公開されたライブ ブランチのコンテンツを直接編集する代わりに、フォークにそのコンテンツのスナップショットを取るので、そこへ変更を加えることができます。

GitHub リポジトリには、1 つ以上の "ブランチ" が含まれています。 ブランチは、プロジェクトのコンテンツ セットを構成するファイルとフォルダーを含む保管単位です。 メイン リポジトリであるかフォークであるかによらず、すべてのリポジトリには、既定のブランチ (通常は "メイン" という名前) と、既定のブランチにマージされることになっている 1 つ以上のブランチが含まれます。 デフォルト ブランチは、プロジェクトの現在のバージョンおよび "信頼できる唯一の情報源" となります。 これは、そのリポジトリ内の他のすべてのブランチの作成元となる親です。

Diagram showing a working branch off of the main branch in a GitHub repo. Changes are made in the working branch then merged back to main.

パブリック リポジトリのドキュメント記事の編集は、ボタン一押しで始まるように見えるかもしれませんが、裏ではいくつかのことが起こっています。 ブラウザーベースの編集プロセスを開始すると、リポジトリのフォークが作成され (まだフォークがない場合)、変更用に使用されます。 編集はフォークのブランチ内で行われ、これは後にメイン リポジトリのライブ ブランチに "マージ" されるため、変更内容をすべてのユーザーが利用できるようになります。

pull request を作成する

このマージはどのように行われますか? GitHub (具体的には、メイン リポジトリの所有者と記事の作成者) に、編集が完了し、レビュー、公開、および世界がそれを見る準備ができていることを伝える必要があります。 これを行うには、pull request を作成して送信します。

pull request (PR) は、自分が作業中のフォーク内のブランチからライブ リポジトリの既定の “メイン” ブランチに変更をマージするための申請です。 パブリック リポジトリで作業する場合、pull request は、マージされる前に、常に人間のレビュー担当者によってレビューされます。 マージの互換性やビルドの検証など、いくつかの自動チェックも存在します。 これらのレビューが完了し、すべての問題が解決されると、変更はライブ ブランチにマージされ、Microsoft Learn で利用できるようになります。

ドキュメントへのマイナー投稿のためのワークフロー

要約すると、GitHub の Web エディターを使用して Microsoft ドキュメントに小さな変更を加える場合は、以下の一般的な手順に従います。

Diagram of the contribution process for contributing to open source documentation on Microsoft Learn.

  1. 編集のためにファイルをブラウザーで開くと、パブリック リポジトリのフォークが自動的に作成されます。 フォーク内のブランチも作成され、多くの場合、パッチ ブランチと呼ばれます。
  2. ファイルに変更を加えます。
  3. 変更内容のレビューとマージを申請する pull request を作成します。
  4. PR はすべての問題を解決し、すべてのレビューに合格する必要があります。
  5. PR がライブ リポジトリのメイン ブランチにマージされ、変更内容が Microsoft Learn で公開されます。

次に、実行方法を確認するために各手順をより詳細に見ていきましょう。