Contributing to the Selenium site & documentation

Information on improving documentation and code examples for Selenium

Selenium is a big software project, its site and documentation are key to understanding how things work and learning effective ways to exploit its potential.

This project contains both Selenium’s site and documentation. This is an ongoing effort (not targeted at any specific release) to provide updated information on how to use Selenium effectively, how to get involved and how to contribute to Selenium.

Contributions toward the site and docs follow the process described in the below section about contributions.

The Selenium project welcomes contributions from everyone. There are a number of ways you can help:

Report an issue

When reporting a new issues or commenting on existing issues please make sure discussions are related to concrete technical issues with the Selenium software, its site and/or documentation.

All of the Selenium components change quite fast over time, so this might cause the documentation to be out of date. If you find this to be the case, as mentioned, don’t hesitate to create an issue for that. It also might be possible that you know how to bring up to date the documentation, so please send us a pull request with the related changes.

If you are not sure about what you have found is an issue or not, please ask through the communication channels described at https://selenium.dev/support.

What to Help With

Creating Examples

Examples that need to be added are marked with:

Add Example

We want to be able to run all of our code examples in the CI to ensure that people can copy and paste and execute everything on the site. So we put the code where it belongs in the examples directory. Each page in the documentation correlates to a test file in each of the languages, and should follow naming conventions. For instance examples for this page https://www.selenium.dev/documentation/webdriver/browsers/chrome/ get added in these files:

  • "/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"

Each example should get its own test. Ideally each test has an assertion that verifies the code works as intended. Once the code is copied to its own test in the proper file, it needs to be referenced in the markdown file.

For example, the tab in Ruby would look like this:

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

The line numbers at the end represent only the line or lines of code that actually represent the item being displayed. If a user wants more context, they can click the link to the GitHub page that will show the full context.

Make sure that if you add a test to the page that all the other line numbers in the markdown file are still correct. Adding a test at the top of a page means updating every single reference in the documentation that has a line number for that file.

Code examples may need a relevant website or web page to demonstrate the scenario. To ensure examples consistently work, it is recommended to use the test web pages available at https://www.selenium.dev/selenium/web/.

Finally, make sure that the tests pass in the CI.

Moving Examples

Examples that need to be moved are marked with:

Move Code

Everything from the Creating Examples section applies, with one addition.

Make sure the tab includes text=true. By default, the tabs get formatted for code, so to use markdown or other shortcode statements (like gh-codeblock) it needs to be declared as text. For most examples, the tabpane declares the text=true, but if some of the tabs have code examples, the tabpane cannot specify it, and it must be specified in the tabs that do not need automatic code formatting.

Contribution Mechanics

The Selenium project welcomes new contributors. Individuals making significant and valuable contributions over time are made Committers and given commit-access to the project.

This guide will guide you through the contribution process.

Step 1: Fork

Fork the project on GitHub and check out your copy locally.

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

Dependencies: Hugo

We use Hugo and the Docsy theme to build and render the site. You will need the “extended” Sass/SCSS version of the Hugo binary to work on this site. We recommend to use Hugo 0.166.0 .

Please follow the Install Hugo instructions from Docsy.

Dependencies: Go

The Docsy theme is pulled in as a Hugo Module, so Hugo needs Go to resolve it when you run hugo server. Install any version satisfying the minimum in go.mod.

Dependencies: Node.js (optional, for the production CSS pipeline)

Node.js is not required to preview the site with hugo server — in development mode Docsy skips PostCSS. You only need Node.js (any current release) if you want your local build to match the production CSS pipeline (autoprefixer/PostCSS), as run by hugo --minify in build-site.sh. In that case, run npm install in website_and_docs first.

Note: This may change with a future Hugo/Docsy upgrade. If theme assets (e.g. Bootstrap/Font Awesome) move from Hugo Modules to npm packages, npm install — and therefore Node.js — could become required for all builds, not just the production pipeline.

Step 2: Branch

Create a feature branch and start hacking:

% git checkout -b my-feature-branch

We practice HEAD-based development, which means all changes are applied directly on top of dev.

Step 3: Make changes

The repository contains the site and docs. To make changes to the site, work on the website_and_docs directory. To see a live preview of your changes, run hugo server on the site’s root directory.