diff options
Diffstat (limited to 'testing/geckodriver/doc/Releasing.md')
| -rw-r--r-- | testing/geckodriver/doc/Releasing.md | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/testing/geckodriver/doc/Releasing.md b/testing/geckodriver/doc/Releasing.md new file mode 100644 index 0000000000..79574f8a0e --- /dev/null +++ b/testing/geckodriver/doc/Releasing.md @@ -0,0 +1,292 @@ +# Releasing geckodriver + +Releasing geckodriver is not as easy as it once used to be when the +project’s canonical home was on GitHub. Today geckodriver is hosted +in [mozilla-central], and whilst we do want to make future releases +from [Mozilla’s CI infrastructure], we are currently in between two +worlds: development happens in m-c, but releases continue to be made +from GitHub. + +In any case, the steps to release geckodriver are as follows: + +[mozilla-central]: https://hg.mozilla.org/mozilla-central/ +[Mozilla’s CI infrastructure]: https://treeherder.mozilla.org/ + +## Update in-tree dependency crates + +geckodriver depends on a number of Rust crates that also live in +central by using relative paths. Here an excerpt from its `Cargo.toml`: + +```ini +[dependencies] +… +marionette = { path = "./marionette" } +… +mozdevice = { path = "../mozbase/rust/mozdevice" } +mozprofile = { path = "../mozbase/rust/mozprofile" } +mozrunner = { path = "../mozbase/rust/mozrunner" } +mozversion = { path = "../mozbase/rust/mozversion" } +… +webdriver = { path = "../webdriver" } +``` + +Because we need to export the geckodriver source code to the old +GitHub repository when we release, we first need to publish these +crates in the specified order if they have had any changes in the +interim since the last release. If they have received no changes, +you can skip them: + +- `testing/mozbase/rust/mozdevice` +- `testing/mozbase/rust/mozprofile` +- `testing/mozbase/rust/mozrunner` +- `testing/mozbase/rust/mozversion` +- `testing/webdriver` +- `testing/geckodriver/marionette` + +For each crate: + +1. Change into the crates folder. +2. Bump the version number in `Cargo.toml` based on [semantic versioning rules], + and also update the version dependency for other in-tree crates using the + currently modified crate. Note that running `cargo update` will fail if you + missed updating a crate's dependency. + +3. Use the [cargo-semver-checks] command to validate the version change: + + ```shell + % cargo semver-checks check-release + ``` + +4. Update the crate: + + ```shell + % cargo update -p <crate name> + ``` + +5. We also publish audit information for the crates based on Mozilla's + [audit criteria]. Because we use [wildcard audit entries] make sure that the + latest day of publication is still within the `end` date. The related entry + of the crate can be found at the top of [audits.toml]. If the date is over, + then update its value to at most 1 year in the future. + +6. Commit the changes for the modified [Cargo.toml] files, [Cargo.lock] and + [audits.toml]. + + ```shell + % git add Cargo.toml Cargo.lock audits.toml testing + % git commit -m "Bug XYZ - [rust-<name>] Release version <version>" + ``` + +[semantic versioning rules]: https://semver.org/ +[cargo-semver-checks]: https://crates.io/crates/cargo-semver-checks +[audit criteria]: https://mozilla.github.io/cargo-vet/audit-criteria.html +[wildcard audit entries]: https://mozilla.github.io/cargo-vet/wildcard-audit-entries.html +[Cargo.toml]: https://searchfox.org/mozilla-central/source/testing/geckodriver/Cargo.toml +[Cargo.lock]: https://searchfox.org/mozilla-central/source/Cargo.lock +[audits.toml]: https://searchfox.org/mozilla-central/source/supply-chain/audits.toml + +## Update the change log + +Notable changes to geckodriver are mentioned in [CHANGES.md]. Many +users rely on this, so it’s important that you make it **relevant +to end-users**. For example, we only mention changes that are visible +to users. The change log is not a complete anthology of commits, +as these often will not convey the essence of a change to end-users. +If a feature was added but removed before release, there is no reason +to list it as a change. + +It is good practice to also include relevant information from the +[webdriver], [marionette], [rust-mozrunner], and [rust-mozdevice] crates, +since these are the most important dependencies of geckodriver and a lot +of its functionality is implemented there. + +To get a list of all the changes for one of the above crates one of the following +commands can be used: + +```shell +% hg log -M -r <revision>::central --template "{node|short}\t{desc|firstline}\n" <path> +% git log --reverse $(git cinnabar hg2git <revision>)..HEAD --pretty="%s" <path> +``` + +where `<revision>` is the changeset of the last geckodriver release and `<path>` +the location of the crate in the repository. + +Add the list of changes to the related release bug on Bugzilla, and also check the +dependency list of the bug for other fixes that are worth mentioning. + +We follow the writing style of the existing change log, with +one section per version (with a release date), with subsections +‘Added’, ‘Changed’, 'Fixed' and ‘Removed’. If the targeted +Firefox or Selenium versions have changed, it is good to make a +mention of this. Lines are optimally formatted at roughly 72 columns +to make the file readable in a text editor as well as rendered HTML. +fmt(1) does a splendid job at text formatting. + +[CHANGES.md]: https://searchfox.org/mozilla-central/source/testing/geckodriver/CHANGES.md +[webdriver]: https://searchfox.org/mozilla-central/source/testing/webdriver +[marionette]: https://searchfox.org/mozilla-central/source/testing/geckodriver/marionette +[rust-mozrunner]: https://searchfox.org/mozilla-central/source/testing/mozbase/rust/mozrunner +[rust-mozdevice]: https://searchfox.org/mozilla-central/source/testing/mozbase/rust/mozdevice + +## Bump the version number and update the support page + +Bump the version number in [Cargo.toml] to the next version. +geckodriver follows [semantic versioning] so it’s a good idea to +familiarise yourself with that before deciding on the version number. + +After you’ve changed the version number, run + +```shell +% ./mach build testing/geckodriver +``` + +again to update [Cargo.lock]. + +Now update the [support page] by adding a new row to the versions table, +including the required versions of Selenium, and Firefox. + +Finally commit all those changes. + +[semantic versioning]: http://semver.org/ +[support page]: https://searchfox.org/mozilla-central/source/testing/geckodriver/doc/Support.md + +## Add the changeset id + +To easily allow a release build of geckodriver after cloning the +repository, the changeset id for the release has to be added to the +change log. Therefore add a final place-holder commit to the patch +series, to already get review for. + +Once all previous revisions of the patch series have been landed, and got merged +to `mozilla-central`, the changeset id from the merge commit has to picked for +finalizing the change log. This specific id is needed because Taskcluster creates +the final signed builds based on that merge. + +## Release new in-tree dependency crates + +Make sure to wait until the complete patch series from above has been +merged to mozilla-central. Then continue with the following steps. + +Before releasing geckodriver all dependency crates as +[updated earlier](#update-in-tree-dependency-crates) have to be +released first. + +Therefore change into each of the directories for crates with an update +and run the following command to publish the crate: + +```shell +% cargo publish +``` + +Note that if a crate has an in-tree dependency make sure to first +change the dependency information. + +Do not release the geckodriver crate yet! + +Once all crates have been published observe the `/target/package/` folder under +the root of the mozilla-central repository and remove all the folders related +to the above published packages (it will save ~1GB disk space). + +## Export to GitHub + +The canonical GitHub repository is <https://github.com/mozilla/geckodriver.git> +so make sure you have a local clone of that. It has three branches: +_master_ which only contains the [README.md]; _old_ which was the +state of the project when it was exported to mozilla-central; and +_release_, from where releases are made. + +Before we copy the code over to the GitHub repository we need to +check out the [release commit that bumped the version number](#add-the-changeset-id) +on mozilla-central: + +```shell +% hg update $RELEASE_REVISION +``` + +Or: + +```shell +% git checkout $(git cinnabar hg2git $RELEASE_REVISION) +``` + +We will now export the contents of [testing/geckodriver] to a new branch that +is based on the _release_ branch, which will be used to create a pull request: + +```shell +% cd $SRC/geckodriver +% git checkout release +% git pull +% git checkout -b do_release_X.Y.Z +% git rm -rf . +% git clean -fxd +% cp -rt $SRC/gecko/testing/geckodriver . +``` + +Now verify that geckodriver builds correctly by running: + +```shell +% cargo build +``` + +[README.md]: https://searchfox.org/mozilla-central/source/testing/geckodriver/README.md +[testing/geckodriver]: https://searchfox.org/mozilla-central/source/testing/geckodriver + +## Commit local changes + +Now commit all the changes you have made locally to the _release_ branch. +It is recommended to setup a [GPG key] for signing the commit, so +that the release commit is marked as `verified`. + +```shell +% git add . -- ':!mach_commands.py :!moz.build :!target/*' +% git commit -S -am "Import of vX.Y.Z" (signed) +``` + +or if you cannot use signing use: + +```shell +% git add . -- ':!mach_commands.py :!moz.build :!target/*' +% git commit -am "Import of vX.Y.Z" (unsigned) +``` + +Then push the changes, and create a pull request: + +```shell +% git push origin do_release_X.Y.Z +``` + +As indicated above, the changes you make to this branch will not +be upstreamed back into mozilla-central. It is merely used as a +place for external consumers to build their own version of geckodriver. + +[GPG key]: https://help.github.com/articles/signing-commits/ + +## Make the release + +geckodriver needs to be manually released on github.com. Therefore start to +[draft a new release], and make the following changes: + +1. Specify the "Tag version", and select "Release" as target. + +2. Leave the release title empty + +3. Paste the raw Markdown source from [CHANGES.md] into the description field. + This will highlight for end-users what changes were made in that particular + package when they visit the GitHub downloads section. Make sure to check that + all references can be resolved, and if not make sure to add those too. + +4. Find the signed geckodriver archives in the [taskcluster index] by + replacing %changeset% with the full release changeset id. Rename the + individual files so the basename looks like 'geckodriver-v%version%-%platform%'. + Upload them all, including the checksum files for the Linux platforms. + +5. Before announcing the release on GitHub publish the geckodriver crate as well + on crates.io by running `cargo publish` from the release branch. + +6. Send the release announcement to the [dev-webdriver] mailing list. + +[draft a new release]: https://github.com/mozilla/geckodriver/releases/new +[taskcluster index]: https://firefox-ci-tc.services.mozilla.com/tasks/index/gecko.v2.mozilla-central.revision.%changeset%.geckodriver +[dev-webdriver]: https://groups.google.com/a/mozilla.org/g/dev-webdriver + +Congratulations! You’ve released geckodriver! |