Releasing Selenium

Release criteria

The release manager needs to evaluate if the codebase is ready for release. This normally involves some subjective judgements. A few things can be noted:

• Tests should be passing for Chrome and Firefox.
• If some test(s) is failing on the CI, execute it locally to determine to confirm its status.
• When you confirm a test failing
  • Determine if the failure is related to the browser/driver. If so, report it to the vendor.
  • Related to Selenium, try to fix the bug but if not possible, check if it blocks the release or not.
• There is no need to have ChromeDriver or GeckoDriver on the PATH, as Selenium Manager is taking care of that.
• Known issues should be added to the release notes.

General

1. Gather feedback from other developers about the release:
   1. Define a time for the release
   2. Ask for release blockers and provide additional details that will help developers participate in the release process.
   3. This should be emailed to 'selenium-developers' though working on IRC/Matrix/Slack alone is just fine.
2. Determine if Selenium Manager needs to be updated for the release. If so:
   1. Execute the Selenium Manager build workflow.
   2. Download the artifacts via curl or wget, take into account that you will need a token. Easiest is to use GitHub CLI. To use GitHub CLI you need to be inside the project's directory so the Git info is available.
   3. Downloaded files need to be uncompressed. If you used GitHub CLI, the .exe will be already uncompressed, but the macOS and Linux will be inside a .tar file. Use the following command to have them uncompressed tar -xvf selenium-manager.tar.
   4. Take the uncompressed files and replace the ones present on the manager directory.
3. Bump the revision numbers at the top of the Rakefile and SELENIUM_VERSION
4. Commit version number bump.
5. To find out the revision of the last release: git log --tags --simplify-by-decoration --pretty="format:%ci %d %h" | sort | tail -1 | awk '{print $NF}'. This will give you the abbreviated hashcode for the last revision.

Create a release

Skip this section if you are doing a patch release

Begin by tagging the revision you're about to release, and push that tag to GitHub.

GitHub Release Page

• Draft a new (perhaps pre-release)
• Make sure this release is for the tag you created earlier
• Set the title to be whatever the release is.
• Use git log $PREV_RELEASE..$NEW_TAG --format=format:'* [%h](https://github.com/seleniumhq/selenium/commit/%H) - %s :: %an' | pbcopy to generate the list of changes. Make sure you've set $PREV_RELEASE and $NEW_TAG!
• The release notes are:

### Changelog

For each component's detailed changelog, please check:
* [Ruby](https://github.com/SeleniumHQ/selenium/blob/trunk/rb/CHANGES)
* [Python](https://github.com/SeleniumHQ/selenium/blob/trunk/py/CHANGES)
* [JavaScript](https://github.com/SeleniumHQ/selenium/blob/trunk/javascript/node/selenium-webdriver/CHANGES.md)
* [Java](https://github.com/SeleniumHQ/selenium/blob/trunk/java/CHANGELOG)
* [DotNet](https://github.com/SeleniumHQ/selenium/blob/trunk/dotnet/CHANGELOG)
* [IEDriverServer](https://github.com/SeleniumHQ/selenium/blob/trunk/cpp/iedriverserver/CHANGELOG)

### Commits in this release
<details>
<summary>Click to see all the commits included in this release</summary>

   INSERT LIST OF CHANGES HERE!

</details>

• Now publish the release.

Java

Prerequisites

1. You can build Selenium (e.g. bazel build grid)
2. Make sure you have an account and permissions to the OSS Sonatype repo. If you do not have an user yet, please go through the initial setup. When creating the Jira ticket to request push access, follow this ticket example.
3. Make sure GnuPG is installed. Detailed instructions can be seen here. Follow the section that mentions how to distribute GnuPG public key. GitHub also has good instructions to generate a key.
4. Make sure you have permission to push to the OSS Sonatype repo. You will need these credentials when pushing the maven release.
5. Make sure your ~/.m2/settings.xml contains the following lines in the <servers> section:

    <server>
        <id>sonatype-nexus-snapshots</id>
        <username>_your-username-for-oss.sonatype.org_</username>
        <password>_your-password_</password>
    </server>
    <server>
        <id>sonatype-nexus-staging</id>
        <username>_your-username-for-oss.sonatype.org_</username>
        <password>_your-password_</password>
    </server>

Release steps

1. Update the Java CHANGELOG under java/CHANGELOG. Do this by finding the revision number of the last release and running git log oldRev..HEAD >> java/CHANGELOG. You'll then need to edit the file by hand.
2. Bump version numbers in the Rakefile and in version.bzl.
3. Update the API docs. See Update API Docs
4. Ensure that the --stamp flag is used by the build. The easiest way to do this is: echo build --stamp >>.bazelrc.local
5. Run ./go clean release-java (this will build and upload everything to sonatype.org and generate the files to upload to GitHub releases)
   1. If you want more control over the release, first release the bindings by running ./go publish-maven, and follow all the OSS Sonatype steps.
   2. Generate the Selenium Grid server jar and other files that will be uploaded to GitHub releases by running ./go prep-release-zip. File will be created in build/dist. If you are doing a patch release, upload the files to the previous major/minor GitHub release.
6. Go to http://oss.sonatype.org, log in, and check that the contents are complete (JARs are there, as well as the signed files). If the contents are looking good, close the staging repository with a meaningful message

.

6. Release the staged release in nexus (or drop it).
   1. If the "Release" button is not enabled, this means that the checks for the repo are still running, you can click on the activity tab to see what activities are pending. This normally takes a few minutes.
7. Make sure any other manual hacks you did are documented in step 5 or committed back on trunk.
8. Once the artifacts finally hit central (please wait till they are actually there), update the downloads page with updated links, release numbers and dates.
   1. Grid Server
   2. Bindings
9. Remove the stamp from .bazelrc.local if added earlier to improve bazel caching
10. Head to the Java examples in our documentation, update the maven version and gradle version through a pull request and verify that all examples still work. Do the same for Kotlin

.NET

To release a new version you will need to be registered as an owner on Nuget.

1. In dotnet/selenium-dotnet-version.bzl

   • Verify the SE_VERSION matches major/minor/patch
   • Verify ASSEMBLY_VERSION matches major Selenium version with minor, patch and build set to zero
   • Verify ASSEMBLY_INFORMATIONAL_VERSION matches major Selenium version

2. Build assets:

   • bazel build --stamp //dotnet/src/webdriver:package
   • bazel build --stamp //dotnet/src/support:package
   • bazel build --stamp //dotnet/src/webdriver:package-strongnamed
   • bazel build --stamp //dotnet/src/support:package-strongnamed

3. Locate assets:

   • bazel-bin/dotnet/src/webdriver/Selenium.WebDriver.x.y.z.nupkg
   • bazel-bin/dotnet/src/webdriver/Selenium.WebDriver.x.y.z.snupkg
   • bazel-bin/dotnet/src/support/Selenium.Support.x.y.z.nupkg
   • bazel-bin/dotnet/src/support/Selenium.Support.x.y.z.snupkg
   • bazel-bin/dotnet/src/webdriver/Selenium.WebDriver.StrongNamed.x.y.z.nupkg
   • bazel-bin/dotnet/src/support/Selenium.Support.StrongNamed.x.y.z.nupkg

4. Copy non-StrongNamed assets to single folder & add to zip file: selenium-dotnet-x.y.z.zip

5. Copy StrongNamed assets to single folder & add to zip file: selenium-dotnet-strongnamed-x.y.z.zip

6. Upload both zip files to Selenium Release directory on Github

7. Push to Nuget:

   • .\third_party\dotnet\nuget\NuGet.exe push .\bazel-bin\dotnet\src\webdriver\Selenium.WebDriver.x.y.z.nupkg -ApiKey XXXYYYZZZAAA -Source https://nuget.org
   • .\third_party\dotnet\nuget\NuGet.exe push .\bazel-bin\dotnet\src\support\Selenium.Support.x.y.z.nupkg -ApiKey XXXYYYZZZAAA -Source https://nuget.org

8. Head to the .NET examples in our documentation, update the version through a pull request and verify that all examples still work.

Ruby

To release a new gem you will need to be registered as a gem owner on rubygems.org.

1. Bump the version number in https://github.com/SeleniumHQ/selenium/blob/trunk/rb/lib/selenium/webdriver/version.rb
2. Update https://github.com/SeleniumHQ/selenium/blob/trunk/rb/CHANGES with a summary of changes since the last release.
3. Run: bazel run --stamp //rb:selenium-webdriver-release
4. Update the downloads page with updated links, release numbers and dates — https://github.com/SeleniumHQ/seleniumhq.github.io/blob/dev/website_and_docs/layouts/partials/selenium-clients-and-webdriver-bindings.html
5. Head to the Ruby examples in our documentation, update the version through a pull request and verify that all examples still work.

Python

To release a new version you need to be registered as a Owner/Maintainer on pypi.python.org

Create a token on pypi and put it in your .pypirc file.

Make sure you have installed twine and it is available on your PATH (pip install twine)

1. Bump the version numbers
   • in setup.py
   • in py/BUILD.bazel
   • in py/README
   • in py/selenium/init.py
   • in py/selenium/webdriver/init.py
   • in py/docs/source/index.rst
   • for major/minor releases, in py/docs/source/conf.py
2. update py/CHANGES file
3. Commit/push
4. bazel build --stamp //py:selenium-wheel //py:selenium-sdist
5. twine upload bazel-bin/py/selenium-4.x.y-py3-none-any.whl bazel-bin/py/selenium-4.x.y.tar.gz
6. See Update API Docs
7. Head to the Python examples in our documentation, update the version through a pull request and verify that all examples still work.

JavaScript

To release a new version you need to be registered as a Owner/Maintainer on npmjs

1. Bump the version number in javascript/node/selenium-webdriver/package.json
2. update changes in javascript/node/selenium-webdriver/CHANGES.md
3. Commit/push
4. Make sure you are authenticated to npmjs.com. You can do that with npm adduser
5. bazel run --stamp //javascript/node/selenium-webdriver:selenium-webdriver.publish
6. Head to the JavaScript examples in our documentation, update the version through a pull request and verify that all examples still work.

Update API Docs

For Java, Ruby and Python:

1. From the root of the repo run: ./generate_api_docs.sh java|rb|py
   1. Example: Run ./generate_api_docs.sh java to update the Java api docs.
2. For the dotnet docs, you need to do that on a Windows machine for now, with the following command in PowerShell
   1. sh .\generate_api_docs.sh dotnet

IE Driver Server

1. Update Atoms (optional)
   • bazel build //javascript/ie-driver:header
   • copy bazel-bin/javascript/ie-driver/atoms.h to cpp/iedriver/Generated directory
2. Open cpp/IEDriverServer.sln in Visual Studio 2022
3. In Solution Explorer tab, right click IEDriver/Resource Files/IEDriver.rc & view code
4. Update version number in 4 places: FILEVERSION, PRODUCTVERSION, FileVersion, ProductVersion
5. In Solution Explorer tab, right click IEDriverServer/Resource Files/IEDriverServer.rc & view code
6. Update version number in 4 places: FILEVERSION, PRODUCTVERSION, FileVersion, ProductVersion
7. Solution Configurations Dropdown in toolbar at top, select Release,
8. In Solution Platform Dropdown, select x64 & in Build menu, select Build Solution
9. In Solution Platform Dropdown, select x86 & in Build menu, select Build Solution
10. In build/cpp/x64/Release/IEDriverServer.exe compress file as IEDriverServer_x64_x.y.z.zip & upload it to Github Release
11. In build/cpp/Win32/Release/IEDriverServer.exe compress file as IEDriverServer_Win32_x.y.z.zip & upload it to Github Release