コンテンツの提出

新しいドキュメントの内容を追加や改善するには、プルリクエスト （PR）を提出してください。

• もし変更が小さかったり、自身が Git に慣れていなかったら、GitHub を使用を参照しページの編集方法を学んでください。
• もしくは、ローカルのフォークから作業するを参照し、ローカルのコンピュータから変更を行う方法を学んでください。

以下の図は新しいドキュメントにコントリビュートする方法を示しています。

図 1. 新しいコンテンツにコントリビュートする。

GitHub を使用

ブラウザから修正し変更を提出する

もし、Git のワークフローをあまり慣れていなければ、プルリクエストを作成して提出するより簡単な方法があります。 図 2 は手順の概要を示しており、詳細はこの後に続きます。

図 2. GitHub を利用した PR の公開手順。

1. 問題を見つけたページ上で、右側のナビゲーションパネルにある ページの編集 のオプションを選択してください。

2. プロジェクトのメンバーでない場合、GitHub でリポジトリのフォークの作成を提案されます。Fork this repositoryを選択してください。

3. GitHub のエディターで、変更を加えます。

4. Propose file change フォームに記入してください。

5. Propose file change を選択します。

6. Create Pull request を選択します。

7. Open a pull request 画面に表示されます。あなたの説明はレビュアーが理解するのに役立ちます。

8. Create pull requestを選択してください。

プルリクエストをマージする前に、OpenTelemetry コミュニティメンバーはレビューして承認します。

レビュアーから変更を求められた場合。

1. File changedタブに移動してください。
2. プルリクエストによって変更されたファイルのいずれかで、鉛筆（編集）アイコンを選択します。
3. 求めら得た変更を加えください。 コードの提案があれば、適用してください。
4. 変更をコミットしてください。

レビューが完了したら、レビュアーは PR をマージして変更が数分後に反映されます。

Fixing PR check failures

PR を提出した後に、GitHub はいくつかのビルドチェックを実行します。 フォーマットの問題といった、特定のチェックの失敗は自動的に修正できます。

以下のコメントを PR に追加してください。

/fix:all

これは、OpenTelemetry bot がビルドの問題を修正しようとします。 もしくは、特定の失敗に対処するために、次の修正コマンドの 1 つを実行できます。

fix:dict
fix:expired
fix:filenames
fix:format
fix:htmltest-config
fix:i18n
fix:markdown
fix:refcache
fix:submodule
fix:text

ローカルで作業する

Git に慣れている場合もしくは、変更が数行以上の場合は、ローカルのフォークから作業してください。

パソコンに git がインストール済みであることを確認してください。 Git のユーザーインターフェースも利用できます。

図 3 は、ローカルのフォークから作業するときに従う手順を示しています。詳細はそれぞれの手順に従ってください。

図 3. ローカルのフォークで作業して変更を追加。

リポジトリをフォークする

1. opentelemetry.io リポジトリに移動してください。
2. フォークを選択してください。

クローンし、アップストリームを設定

1. ターミナルウィンドウで、フォークをクローンし、必要なものをインストールしてください。

   git clone git@github.com:<your_github_username>/opentelemetry.io.git
   cd opentelemetry.io
   npm install
   

2. open-telemetry/opentelemetry.io リポジトリを upstream リモートに設定。

   git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git
   

3. origin と upstream リポジトリの確認。

   git remote -v
   

   出力は以下のようになります。

   origin	git@github.com:<your_github_username>/opentelemetry.io.git (fetch)
   origin	git@github.com:<your_github_username>/opentelemetry.io.git (push)
   upstream	https://github.com/open-telemetry/opentelemetry.io.git (fetch)
   upstream	https://github.com/open-telemetry/opentelemetry.io.git (push)
   

4. フォークの origin/main と open-telemetry/opentelemetry.io の upstream/main からコミットをフェッチ。

   git fetch origin
   git fetch upstream
   

   これにより、変更を加える前にローカルリポジトリが最新の状態であることを確認できます。 フォークをアップストリームと同期させるために、定期的にアップストリームの変更をオリジンにプッシュしてください。

ブランチを作成

1. 新しいブランチを作成します。 この例はベースブランチが upstream/main であると想定しています。

   git checkout -b <my_new_branch> upstream/main
   

2. コードエディターまたはテキストエディターを使用して変更を加えてください。

いつでも、git status コマンドを使用して、どのファイルが変更したか確認できます。

変更のコミット

プルリクエストを提出する準備ができたら、変更をコミットしてください。

1. ローカルリポジトリで、コミットが必要なファイルを確認してください。

   git status
   

   出力は次のようになります。

   On branch <my_new_branch>
   Your branch is up to date with 'origin/<my_new_branch>'.
   
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
   modified:   content/en/docs/file-you-are-editing.md
   
   no changes added to commit (use "git add" and/or "git commit -a")
   

2. Changes not staged for commit のリストされているファイルをコミットしてください。

   git add <your_file_name>
   

   これを各ファイルに対して繰り返してください。

3. すべてのファイルを追加した後に、 コミットを作成してください。

   git commit -m "Your commit message"
   

4. ローカルブランチと新しいコミットをリモートのフォークにプッシュしてください。

   git push origin <my_new_branch>
   

5. 変更がプッシュされると、GitHub が PR を作成できることを知らせます。

新しいプルリクエストを公開する

図 4 はフォークから opentelemetry.io への PR を開く手順を示しています。

図 4. フォークから、PR を公開する手順 opentelemetry.io.

1. Web ブラウザで opentelemetry.io リポジトリにアクセスしてください。
2. New Pull Request を作成してください。
3. compare across forks を選択してください。
4. head repository ドロップダウンメニューから、あなたのフォークを選択してください。
5. ドロップダウンメニューの compare から、あなたのブランチを選択してください。
6. Create Pull Request を選択してください。
7. プルリクエストの説明を追加してください。
   • タイトル (50 文字未満): 変更の意図を要約してください。
   • 説明: 変更を詳細に記述してください。
     • GitHub イシューに関連する場合、Fixes #12345 や Closes #12345 を説明に記述することで、PR のマージしたあとに GitHub の自動化が該当イシューをクローズします。 他の関連する PR がある場合もリンクしてください。
     • 特定のことに対してアドバイスを求める場合、説明にレビュアーが考えて欲しい質問を含めてください。
8. Create pull request ボタンを選択してください。

プルリクエストは、Pull requests で確認できます。

PR を公開した後に、自動テストの実行と Netlify を使用したプレビューのデプロイを試みます。

• Netlify ビルドが失敗した場合、詳細な情報のために Details を選択してください。
• Netlify のビルドが成功した場合、Details を選択して、変更が適用された OpenTelemetry のウェブサイトのステージングバージョンを開いてください。 これがレビュアーが変更を確認する方法です。

他のチェックも同様に失敗している可能性があります。すべての PR チェック を参照してください。

問題を修正する

リポジトリに変更を提出するまえに、以下のコマンドを実行して (i) 報告された問題の対応し、(ii) スクリプトによって変更されたファイルのコミットをしてください。

npm run test-and-fix

ファイルに対して、テストとすべての問題の修正を分割して実行するには、以下を実行してください。

npm run test    # ファイルを更新せずにチェックのみを実行します
npm run fix:all # ファイルを更新する場合があります。

利用可能な NPM スクリプトのリストを表示するには、npm run を実行してください。 プルリクエストのチェックとエラーの自動修正の詳細は、PR checks を参照してください。

変更をプレビューする

変更のプッシュまたはプルリクエストの公開の前に、ローカルでプレビューしてください。 プレビューはビルドエラーとマークダウンのフォーマットの問題を検出できます。

Hugo をローカルでビルドと提供するには、以下のコマンドを実行してください。

npm run serve

Web ブラウザで http://localhost:1313 に移動してローカルプレビューを確認してください。 Hugo は変更を監視し、必要に応じてサイトをリビルドします。

ローカルの Hugo インスタンスを停止するには、ターミナルにもどって Ctrl+C を入力するか、ターミナルを閉じてください。

サイトデプロイと PR プレビュー

PR を提出したら、Netlify は deploy preview を作成し、変更をレビューできます。 PR がマージされると、Netlify はプロダクションサーバーに更新されたサイトを本番サーバーにデプロイします。

Note: PR プレビューには ドラフトページ が含まれますが、本番ビルドには含まれません。

デプロイログなどを確認するには、プロジェクトの dashboard を確認してください。 Netlify ログインが必要です。

PR ガイドライン

PR がマージされる前に、レビューと編集を数回繰り返すことがあります。 このプロセスをできるだけ簡単にするために、以下のガイドラインに従ってください。

• もしあなたの PR が簡単な修正でない場合は、フォークから作業してください。 リポジトリの上部にある Fork ボタンをクリックし、フォークをローカルにクローンしてください。準備ができたら、アップストリームリポジトリに PR を作成してください。
• あたなたのフォークの main ブランチから作業をせずに、PR 専用のブランチを作成してください。
• メンテナーがあなたのプルリクエストに変更を加えられることを確認してください。

レビュアーからの変更

レビュアーはあなたのプルリクエストにコミットすることがあります。 ほかの変更を加える前に、それらのコミットをフェッチしてください。

1. リモートフォークからコミットをフェッチして、作業中のブランチをリベースしてください。

   git fetch origin
   git rebase origin/<your-branch-name>
   

2. リベースしたあとに、フォーク先にあなたの変更をフォースプッシュしてください。

   git push --force-with-lease origin <your-branch-name>
   

コンフリクトは GitHub UI からも解決できます。

マージのコンフリクトとリベース

別のコントリビューターが別の PR で同じファイルに変更をコミットすると、マージコンフリクトが発生する可能性があります。 あなたの PR ですべてのマージコンフリクトを解決する必要があります。

1. フォークを更新して、ローカルブランチをリベースしてください。

   git fetch origin
   git rebase origin/<your-branch-name>
   

   フォークに変更をフォースプッシュしてください。

   git push --force-with-lease origin <your-branch-name>
   

2. open-telemetry/opentelemetry.io の upstream/main から変更をフェッチして、あなたのブランチをリベースしてください。

   git fetch upstream
   git rebase upstream/main
   

3. リベースの結果を確認してください。

   git status
   

   これにより、多くのファイルがコンフリクトとしてマークされます。

4. コンフリクトが発生した各ファイルを開き、コンフリクトマーカー（>>>、<<< そして ===） を探してください。 コンフリクトを解消してコンフリクトマーカーを削除してください。

   詳細は、How conflicts are presented を確認してください。

5. ファイルをチェンジセットに追加してください。

   git add <filename>
   

6. リベースを続けてください。

   git rebase --continue
   

7. ステップ 2 から 5 を必要に応じて繰り返してください。

   すべてのコミットを適用した後、git status コマンドはリベースが完了したことを示します。

8. ブランチをあなたのフォークにフォースプッシュしてください。

   git push --force-with-lease origin <your-branch-name>
   

   プルリクエストにはもうコンフリクトが表示されません。

マージの要件

プルリクエストは、以下の条件を満たしたときにマージされます。

• 承認者、メンテナー、技術委員会メンバー、または専門家によるすべてのレビューが “Approved” ステータスであること。
• 解決していない会話がないこと。
• 最低 1 人の承認者によって承認されていること。
• 失敗している PR チェックがないこと。
• PR ブランチがベースブランチと最新の状態であること。
• ドキュメントページの変更がロケールをまたいでいないこと

重要

PR チェックの失敗についてあまり心配しないでください。 コミュニティメンバーが修正方法を教えたり、代わりに修正したりしてくれます。