Seleniumサイトとドキュメントへの貢献

Selenium のドキュメントとコード例を改善するための情報

Selenium は大規模なソフトウェアプロジェクトであり、そのサイトとドキュメントは、Selenium の仕組みを理解し、その潜在能力を効果的に活用する方法を学ぶための鍵となります。

このプロジェクトには、Selenium のサイトとドキュメントの両方が含まれています。これは、Selenium を効果的に使用する方法、参加する方法、Selenium に貢献する方法に関する最新情報を提供するための継続的な取り組み（特定のリリースを対象としたものではありません）です。

サイトとドキュメントへの貢献は、貢献に関する以下のセクションで説明されているプロセスに従います。

Selenium プロジェクトは、すべての人からの貢献を歓迎します。貢献できる方法はたくさんあります。

issue を報告

新しい issue を報告したり、既存の issue にコメントしたりする場合は、議論が Selenium ソフトウェア、そのサイト、および/またはドキュメントに関する具体的な技術的な問題に関連していることを確認してください。

Selenium のすべてのコンポーネントは時間の経過とともに非常に速く変化するため、ドキュメントが古くなっている可能性があります。そのような場合は、前述のように、遠慮なく issue を作成してください。また、ドキュメントを最新の状態にする方法を知っている可能性もありますので、関連する変更を含むプルリクエストをお送りください。

発見したものが issue かどうか不明な場合は、https://selenium.dokyumento.jp/support で説明されているコミュニケーションチャネルを通じてお問い合わせください。

貢献できること

例を作成する

移動する必要がある例は、次のようにマークされています

例を追加

すべてのコード例を CI で実行できるようにして、サイト上のすべてのものをコピー＆ペーストして実行できるようにしたいと考えています。そのため、コードは examples ディレクトリの適切な場所に配置します。ドキュメントの各ページは、各言語のテストファイルに対応しており、命名規則に従う必要があります。たとえば、このページ https://selenium.dokyumento.jp/documentation/webdriver/browsers/chrome/ の例は、次のファイルに追加されます

  • /examples/java/src/test/java/dev/selenium/browsers/ChromeTest.java
  • /examples/python/tests/browsers/test_chrome.py
  • /examples/dotnet/SeleniumDocs/Browsers/ChromeTest.cs
  • /examples/ruby/spec/browsers/chrome_spec.rb
  • /examples/javascript/test/browser/chromeSpecificCaps.spec.js

各例には独自のテストが必要です。理想的には、各テストにはコードが意図したとおりに動作することを検証するアサーションが含まれています。コードが適切なファイル内の独自のテストにコピーされたら、markdown ファイルで参照する必要があります。

たとえば、Ruby のタブは次のようになります

    {{< tab header="Ruby" >}}
    {{< gh-codeblock path="/examples/ruby/spec/browsers/chrome_spec.rb#L8-L9" >}}
    {{< /tab >}}

末尾の行番号は、実際に表示されている項目を表すコードの行または行のみを表します。ユーザーがより多くのコンテキストが必要な場合は、GitHub ページへのリンクをクリックすると、完全なコンテキストが表示されます。

ページにテストを追加する場合は、markdown ファイル内の他のすべての行番号がまだ正しいことを確認してください。ページの先頭にテストを追加すると、そのファイルの行番号を持つドキュメント内のすべての参照を更新する必要があることを意味します。

最後に、テストが CI でパスすることを確認してください。

例を移動する

移動する必要がある例は、次のようにマークされています

コードを移動

「例を作成する」セクションのすべてが適用されますが、1 つ追加があります。

タブに text=true が含まれていることを確認してください。デフォルトでは、タブはコード用にフォーマットされるため、markdown またはその他のショートコードステートメント（gh-codeblock など）を使用するには、テキストとして宣言する必要があります。ほとんどの例では、tabpane が text=true を宣言しますが、一部のタブにコード例がある場合、tabpane はそれを指定できず、自動コードフォーマットを必要としないタブで指定する必要があります。

貢献の仕組み

Selenium プロジェクトは、新しい貢献者を歓迎します。長年にわたって重要かつ価値のある貢献をしている個人は、コミッターにされ、プロジェクトへのコミットアクセス権が与えられます。

このガイドでは、貢献プロセスについて説明します。

ステップ 1: フォーク

GitHub でプロジェクトをフォークし、ローカルコピーをチェックアウトします。

% git clone git@github.com:seleniumhq/seleniumhq.github.io.git
% cd seleniumhq.github.io

依存関係: Hugo

サイトを構築およびレンダリングするために、Hugo と Docsy テーマを使用しています。このサイトで作業するには、Hugo バイナリの「拡張」Sass/SCSS バージョンが必要です。Hugo 0.125.4 を使用することをお勧めします。

Docsy の「Hugo のインストール」手順に従ってください。

ステップ 2: ブランチ

機能ブランチを作成して開発を始めましょう

% git checkout -b my-feature-branch

HEAD ベースの開発を実践しています。これは、すべての変更が dev の上に直接適用されることを意味します。

ステップ 3: 変更を加える

リポジトリには、サイトとドキュメントが含まれています。サイトに変更を加えるには、website_and_docs ディレクトリで作業します。変更のライブプレビューを表示するには、サイトのルートディレクトリで hugo server を実行します。

% cd website_and_docs
% hugo server

プロジェクトは GitHub からコードをロードします。そのコードが更新されていて、プレビューに反映されていない場合は、キャッシュなしで hugo を実行できます: hugo server --ignoreCache

貢献に関する規約の詳細については、スタイルガイドを参照してください

ステップ 4: コミット

まず、git があなたの名前とメールアドレスを知っていることを確認してください

% git config --global user.name 'Santa Claus'
% git config --global user.email 'santa@example.com'

適切なコミットメッセージを書くことは重要です。 コミットメッセージは、何が変更されたのか、なぜ変更されたのか、および修正された issue (もしあれば) を記述する必要があります。コミットメッセージを書く際には、次のガイドラインに従ってください

  1. 最初の行は 50 文字程度以内とし、変更の簡単な説明を含める必要があります。
  2. 2 行目は空白にしてください。
  3. 他のすべての行を 72 カラムで折り返してください。
  4. Fixes #N を含めます。N は、コミットが修正する issue 番号 (もしあれば) です。

適切なコミットメッセージは次のようになります

explain commit normatively in one line

Body of commit message is a few lines of text, explaining things
in more detail, possibly giving some background about the issue
being fixed, etc.

The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
72 characters or so. That way `git log` will show things
nicely even when it is indented.

Fixes #141

最初の行は、git shortlog または git log --oneline を実行したときに人々が見るものであるため、意味のあるものでなければなりません。

ステップ 5: リベース

git rebase (git merge ではなく) を使用して、作業を時々同期してください。

% git fetch origin
% git rebase origin/trunk

ステップ 6: テスト

常にローカルサーバーを実行することを忘れないでください。これにより、変更によって何も壊れていないことを確認できます。

ステップ 7: プッシュ

% git push origin my-feature-branch

https://github.com/yourusername/seleniumhq.github.io.git にアクセスし、「Pull Request」を押してフォームに記入してください。CLA に署名したことを示してください (ステップ 7 を参照)。

プルリクエストは通常、数日以内にレビューされます。対処すべきコメントがある場合は、新しいコミット (できれば fixups) で変更を適用し、同じブランチにプッシュしてください。

ステップ 8: 統合

コードレビューが完了すると、コミッターがあなたの PR を受け取り、リポジトリの trunk ブランチに統合します。trunk ブランチで線形履歴を維持したいので、通常はブランチ履歴を squash および rebase します。

コミュニケーション

プロジェクトの貢献者およびコミュニティ全体とのコミュニケーション方法に関するすべての詳細は、https://selenium.dokyumento.jp/support にあります

最終更新日: 2024年8月27日: ビルドエラーを回避するために、貢献の hugo バージョンを 0.125.4 に更新 (#1899) (00251f47fc1)