Microsoft Learn ドキュメントに大きな変更を加える

  • [アーティクル]

重要

Microsoft Learn に発行されるすべてのリポジトリには、「Microsoft オープンソース行動規範」または「.NET Foundation 行動規範」が適用されます。 詳細については、倫理規定に関する FAQ を参照してください。 または、ご質問やコメントがある場合は、opencode@microsoft.com または conduct@dotnetfoundation.org までご連絡ください。

パブリック リポジトリに含まれているドキュメントとコード例に対する軽微な修正や明確化は、learn.microsoft.com の使用条件の対象になります。 Microsoft の従業員ではない共同作成者が変更を行うと、オンライン貢献者使用許諾契約書 (CLA) の提出をお願いするコメントがプルリクエスト内に生成されます。 Pull request をマージするには、オンライン フォームへの入力が必要になります。

この記事は、ローカル ツールを使用して Microsoft Learn の記事を変更する方法を示し、大規模な変更を行う必要がある共同作成者や、リポジトリへの変更を頻繁に行う共同作成者に適しています。 概して、頻繁に作業をする共同作成者とは、pull request (PR) のサインオフに至るまでに、ビルド/検証/ステージングのサイクルを何度も繰り返す継続的な変更や、何日もかかる長期変更を抱えている共同作成者のことです。

このタイプの共同作成の例:

  • 大規模な投稿を行う。 たとえば、投稿 (追加、変更、削除) は、複数の記事にまたがり、1 つの PR で 1 つの作業単位としてコミットおよびテストする必要がある場合があります。
  • 新しい記事の作成と発行。一般的に、より堅牢なローカル エディターが必要になります。
  • 新しいイメージの追加またはイメージの更新。一般的に、新しい media サブディレクトリを同時に作成し、イメージ ファイルを作成し、記事のイメージ リンクを更新し、ローカル エディターでマークダウン ファイルをプレビューしてイメージのレンダリングをテストする必要があります。
  • 公開前の一定期間、記事を更新する。 そのような場合、一般的に、デフォルト ブランチで発生する他の変更の通常統合を行う必要があります。 この統合は、Git Bash とローカル編集を利用すれば簡単にできます。 GitHub ウェブ エディター経由でこれを行う場合、変更のコミットを待つ間、編集内容が失われてしまう可能性もあります。
  • PR が開かれた後、同じ記事を継続的に更新する。 この目的で GitHub Web エディターを使用できますが、同じファイルに対して複数の未処理の PR を作成できます。これは互いに競合する可能性があります。

前提条件

作業ブランチを作成してチェックアウトする

まず、ローカル リポジトリに新しい作業ブランチを作成して、提案された変更をキャプチャします。 ブランチの詳細については、Git と GitHub の基礎を参照してください。

このチュートリアルでは、Git Bash と Visual Studio Code を使用しますが、任意の Git クライアントとエディターを使用することもできます。

  1. VS Code で、ローカル クローンのリポジトリ フォルダーを開きます。 [ファイル] メニューから、[フォルダーを開く] を選択し、コンピューター上のフォルダーに移動します。

  2. 上部のメニューから [表示] を選択し、[ターミナル] を選択して統合ターミナルを開きます。

  3. 統合ターミナルで、リポジトリ フォルダーにいることを確認します。

  4. 作業ブランチを作成する前に、ローカル メイン ブランチが運用リポジトリの メイン ブランチ内のすべてで最新であることを確認します。 このタスクにより、最後に同期した時点以降に運用リポジトリで発生したすべての変更が、作業ブランチによって確実にキャプチャされます。

    1. ローカル リポジトリの メイン ブランチに切り替えます。

      git checkout main

    2. ローカル メイン ブランチが最新であることを確認します。

      git pull upstream main

  5. メインに基づいてローカル作業ブランチを作成します。

    git checkout -b <branch-name>

    <branch-name> は、プレースホルダーです。 コマンドを実行するときは、ブランチの一意でわかりやすい名前に置き換え、山かっこを削除します。

  6. ローカル作業ブランチを GitHub フォークのリモート ブランチにプッシュします。

    git push origin <branch-name> -u

    -u オプションは、ローカルブランチとリモートブランチをリンクします。 このオプションを使用すると、単に git push を git push origin <branch-name> の代わりに入力して、フォークにコミットをプッシュすることができます。

ソース マークダウン ファイルを検索する

記事を編集するには、ローカル リポジトリの複製で記事のソース ファイルを見つけます。 VS Code 内で、エクスプローラー (左上のサイドバーのドキュメント アイコン) を使用してリポジトリの Markdown ファイルにアクセスします。 ファイル エクスプローラーにはリポジトリのフォルダー構造が表示され、編集するファイルに移動できます。

ファイルが見つからない場合は、Microsoft Learn の記事にアクセスし、[編集] 鉛筆アイコンを選択します。 GitHub リポジトリ内の相対フォルダーの場所が URL に表示されます。 リンク URL の編集の例を次に示します。

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

この URL のファイルの場所の例を次に示します。

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

ファイルを編集する

  1. VS Code でファイルを選択して開きます。
  2. 変更を行います。
  3. [ファイル]>[保存] を選択して、変更を保存します。 [すべて保存] を使用して、複数のファイルを一度に保存します。

コミットし、変更をプッシュする

大幅な編集を行った場合、または記事の新しさを確認した場合は、ファイルの上部のメタデータ ブロックにある ms.date を更新します。 日付は mm/dd/yyyy の形式で設定します。

VS Code ターミナルまたは VS Code UI を使用して、変更をコミットしてプッシュできます。

  1. git status コマンドを実行して、編集したファイルのみが変更されたファイルの一覧に表示されることを確認します。

    git status

  2. ファイル パスとファイル名が後に続く git add コマンドを実行して、変更したファイルをステージングします。

    git add folder-name/file-name.md

    複数のファイルを変更した場合は、各ファイルで git add コマンドを入力します。

    あるいは、git add . (add の後のピリオドに注意) を実行して、行ったすべての変更を自動的にステージングすることもできます。 この方法は高速ですが、誤って行った変更を含めることで問題を引き起こす可能性があります。

  3. もう一度 git status を実行して、ステージングされた変更を確認します。

  4. コミット メッセージが後に続く git commit コマンドを実行して、ローカルの複製されたリポジトリに変更を保存します。

    git commit -m "your commit message"

  5. git push を実行して変更をプッシュします。

    git push

完了しました。 これで自分のコードが自分の GitHub リポジトリにアップロードされ、PR を開く準備が整いました。

送信したものを修正する必要がありますか? これは簡単にできます。 [ファイルの編集] から始まる上記の手順を繰り返して、同じブランチに変更を加え、再度コミットしてプッシュするだけです (同じブランチの後続のプッシュでアップストリーム サーバーを設定する必要はありません)。 通常、ブランチは作業のストリームを分離するために使用されるため、別の作業を行う準備が整っていない限り、新しいブランチを作成する必要はありません。

次の変更を行う

この変更とは無関係に、別の変更を行う準備は整いましたか? 既定のブランチに戻り、アップストリーム リポジトリからプルして、フォークを更新し、新しいブランチをチェックアウトします。 Git Bash で次のコマンドを実行します。

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

これで、リモート ブランチにリンクされた新しいブランチが作成され、さらに変更を加える準備ができました。 エキスパートの共同作成者になる準備が整いました!

次のステップ

  • 上記の手順を完了したならば、PR を開いて、変更をメイン ブランチにマージすることができます。
  • Markdown や Markdown 拡張構文などのトピックの詳細については、「Markdown リファレンス」を確認してください。