Microsoft Learn の投稿の基礎
投稿プロセスを理解して完了するのに役立つ知っておくべき用語がいくつかあります。 内部で起こっていることすべてを知る必要はありませんが、コントリビューションがどのように行われるかの概要を把握することは、プロセスがなぜそのようになっているのかを理解する上で役立ちます。
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 つ以上のブランチが含まれています。 既定のブランチは、プロジェクトの現在のバージョンおよび "信頼できる唯一の情報源" となります。 これは、そのリポジトリ内の他のすべてのブランチの作成元となる親です。
パブリック リポジトリ内のドキュメント記事の編集は、ボタン一押しで始まるように見えるかもしれませんが、裏ではいくつかのことが起こっています。 ブラウザーベースの編集プロセスを開始すると、リポジトリのフォークが作成され (まだフォークがない場合)、変更用に使用されます。 編集はフォークのブランチ内で行われ、これは後にメイン リポジトリのライブ ブランチに "マージ" されるため、変更内容をすべてのユーザーが利用できるようになります。
pull request を作成する
このマージはどのように行われますか? GitHub (具体的には、メイン リポジトリの所有者とその記事の作成者) に、自分の編集作業が完了し、レビューと公開を行って、世界中の人に見えるようにする準備ができていることを伝える必要があります。 これを行うには、pull request を作成して送信します。
pull request (PR) は、自分が作業中のフォーク内のブランチからライブ リポジトリの既定の "メイン" ブランチに変更をマージするための申請です。 パブリック リポジトリ内で作業している場合、pull request は、マージされる前に、常に人間のレビュー担当者によってレビューされます。 マージの互換性やビルドの検証など、いくつかの自動チェックも存在します。 これらのレビューが完了し、すべての問題が解決されると、変更はライブ ブランチにマージされ、Microsoft Learn で利用できるようになります。
ドキュメントへのマイナー投稿のためのワークフロー
要約すると、GitHub の Web エディターを使用して Microsoft ドキュメントに小さな変更を加える場合は、以下の一般的な手順に従うことになります。
- 編集のためにファイルをブラウザーで開くと、パブリック リポジトリのフォークが自動的に作成されます。 フォーク内のブランチも作成され、多くの場合、パッチ ブランチと呼ばれます。
- ファイルに変更を加えます。
- 変更内容のレビューとマージを申請する pull request を作成します。
- PR はすべての問題を解決し、すべてのレビューに合格する必要があります。
- PR がライブ リポジトリのメイン ブランチにマージされ、変更内容が Microsoft Learn で公開されます。
次に、各手順の実行方法を確認するためにそれぞれを詳細に見ていきましょう。