diff options
Diffstat (limited to 'doc/Releasing.md')
| -rw-r--r-- | doc/Releasing.md | 146 |
1 files changed, 92 insertions, 54 deletions
diff --git a/doc/Releasing.md b/doc/Releasing.md index 491cb76..9618045 100644 --- a/doc/Releasing.md +++ b/doc/Releasing.md @@ -6,12 +6,7 @@ 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 using Travis. - -The reason for this is that we do not compile geckodriver for all -our target platforms, that Rust cross-compilation on TaskCluster -builders is somewhat broken, and that tests are not run in automation. -We intend to fix all these problems. +from GitHub. In any case, the steps to release geckodriver are as follows: @@ -19,14 +14,15 @@ In any case, the steps to release geckodriver are as follows: [Mozilla’s CI infrastructure]: https://treeherder.mozilla.org/ -Release new in-tree dependency crates -------------------------------------- +Update in-tree dependency crates +-------------------------------- geckodriver depends on a number of Rust crates that also live in central by using relative paths: [dependencies] … + mozdevice = { path = "../mozbase/rust/mozdevice" } mozprofile = { path = "../mozbase/rust/mozprofile" } mozrunner = { path = "../mozbase/rust/mozrunner" } mozversion = { path = "../mozbase/rust/mozversion" } @@ -36,8 +32,9 @@ central by using relative paths: Because we need to export the geckodriver source code to the old GitHub repository when we release, we first need to publish these crates if they have had any changes in the interim since the last -release. If they have receieved no changes, you can skip them: +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` @@ -46,7 +43,9 @@ release. If they have receieved no changes, you can skip them: For each crate: 1. Bump the version number in Cargo.toml - 2. `cargo publish` + 2. Update the crate: `cargo update -p <crate name>` + 3. Commit the changes for the modified `Cargo.toml`, and `Cargo.lock` + (can be found in the repositories root folder) Update the change log @@ -67,14 +66,14 @@ is implemented there. We follow the writing style of the existing change log, with one section per version (with a release date), with subsections -‘Added’, ‘Changed’, and ‘Removed’. If the targetted +‘Added’, ‘Changed’, 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 -[rust-mozrunner]: https://github.com/jgraham/rust_mozrunner +[rust-mozrunner]: https://searchfox.org/mozilla-central/source/testing/mozbase/rust/mozrunner Update libraries @@ -85,32 +84,68 @@ Make relevant changes to [Cargo.toml] to upgrade dependencies, then run % ./mach vendor rust % ./mach build testing/geckodriver -to pull down and vendor the upgraded libraries. Remember to check -in the [Cargo.lock] file since we want reproducible builds for -geckodriver, uninfluenced by dependency variations. +to pull down and vendor the upgraded libraries. The updates to dependencies should always be made as a separate commit to not confuse reviewers, because vendoring involves checking in a lot of extra code already reviewed downstream. [Cargo.toml]: https://searchfox.org/mozilla-central/source/testing/geckodriver/Cargo.toml -[Cargo.lock]: https://searchfox.org/mozilla-central/source/testing/geckodriver/Cargo.lock +[Cargo.lock]: https://searchfox.org/mozilla-central/source/Cargo.lock -Bump the version number ------------------------ +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 wih that before deciding on the version number. +familiarise yourself with that before deciding on the version number. After you’ve changed the version number, run % ./mach build testing/geckodriver -again to update [Cargo.lock], and check in the file. +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 reviewed and +landed, it's known which commit id the version bump commit has, finalize the +change log, and land that remaining revision. + + +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: + + % cargo publish + +Note that if a crate has an in-tree dependency make sure to first +change the dependency information. Export to GitHub @@ -126,23 +161,24 @@ 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 [commit we made earlier](#bump-the-version-number) -against central that bumped the version number: +check out the [release commit that bumped the version number](#add-the-changeset-id) +on mozilla-central: - % git checkout $BUMP_REVISION + % hg update $RELEASE_REVISION Or: - % hg update $BUMP_REVISION + % git checkout $RELEASE_REVISION We will now export the contents of [testing/geckodriver] to the _release_ branch: % cd $SRC/geckodriver % git checkout release + % git pull % git rm -rf . % git clean -fxd - % cp -r $SRC/gecko/testing/geckodriver . + % cp -rt $SRC/gecko/testing/geckodriver . [README.md]: https://searchfox.org/mozilla-central/source/testing/geckodriver/README.md [testing/geckodriver]: https://searchfox.org/mozilla-central/source/testing/geckodriver @@ -154,7 +190,7 @@ Manually change in-tree path dependencies After the source code has been imported we need to change the dependency information for the `mozrunner`, `mozprofile`, `mozversion`, and `webdriver` crates. As explained previously geckodriver depends -on a relative path in in the mozilla-central repository to build +on a relative path in the mozilla-central repository to build with the latest unreleased source code. This relative paths do not exist in the GitHub repository and the @@ -167,51 +203,53 @@ made to it since the last geckodriver release. Commit local changes -------------------- -Now commit all the changes you have made locally to the _release_ branch: +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`. % git add . - % git commit -am "import of vX.Y.Z" + % git commit -S -am "import of vX.Y.Z" (signed) -As indicated above, the changes you make to this branch will not -be upstreamed back into mozilla-central. It is merely used as a -staging ground for pushing builds to Travis. +or if you cannot use signing use: + % git add . + % git commit -am "import of vX.Y.Z" (unsigned) -Tag the release ---------------- +Then push the changes: -Run the following command to tag the release: + % git push - % git tag 'vX.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 is released and automatically uploaded from Travis by -pushing a new version tag to the _release_ branch: +geckodriver needs to be manually released on github.com. Therefore start to +[draft a new release], and make the following changes: - % git push - % git push --tags +1. Specify the "Tag version", and select "Release" as target. +2. Leave the release title empty -Update the release description ------------------------------- +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. -Copy the raw Markdown source from [CHANGES.md] into the description -of the [latest release]. This will highlight for end-users what -changes were made in that particular package when they visit the -GitHub downloads section. +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 both the Linux platforms. -Congratulations! You’ve released geckodriver! +[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 -[latest release]: https://github.com/mozilla/geckodriver/releases +Congratulations! You’ve released geckodriver! -Future work ------------ - -In the future, we intend to [sign releases] so that they are -verifiable. - -[sign releases]: https://github.com/mozilla/geckodriver/issues/292 +[releases page]: https://github.com/mozilla/geckodriver/releases |