Document back-porting process for maintainers (#4888)

* start documenting back port process * first iteration of backport script * set labels after successful backport * fix parameter * set proper order * ensure that user run fetch all * more docs * add example * add note to export a GITHUB_AUTH token * split up doc add for smoke tests * PR feedback * add missing comment * better define when to backport changes
2019-12-17 15:00:43 +01:00 · 2019-12-17 15:00:43 +01:00 · ec7d822aaa
commit ec7d822aaa
parent 77dc52fdb8
4 changed files with 188 additions and 4 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -23,7 +23,7 @@ In order to set up this project and start contributing follow this step by step

    ```sh
    $ npm install
-    $ npm run setup
+    $ npm run setup-full
    ```

    * Bootstraps sub-projects via ```npm run bootstrap```
@ -98,6 +98,58 @@ npm link @wdio/cli

 In order to test certain scenarios this project has a test directory that allows you to run predefined test. It allows you to check your code changes while you are working on it. You find all these files in `/examples`. You find all necessary information [in there](https://github.com/webdriverio/webdriverio/tree/master/examples/README.md).

+## Back-Porting Bug Fixes
+
+Starting from v6 the WebdriverIO team tries to backport all features that would be still backwards compatible with older versions. The team tries to release a new major version every year (usually around December/January). With a new major version update (e.g. v6) we continue to maintain the last version (e.g. v5) and depcrecate the previous maintained version (e.g. v4). With that the team commits to always support 2 major versions.
+
+### As Triager
+
+Everyone triaging or reviewing a PR should label it with `backport-requested` if the changes can be applied to the maintained (previous) version. Generally every PR that would not be a breaking change for the previous version should be considered to be ported back. If a change relies on features or code pieces that are only available in the current version then a back port can still be considered if you feel comfortable making the necessary adjustments. That said, don't feel forced to back port code if the time investment and complexity is too high. Backporting functionality is a reasonable contribution that can be made by any contributor.
+
+### As A Merger
+
+Once a PR with a `backport-requested` label got merged, you are responsible for backporting the patch to the older version. To do so, pull the latest code from GitHub:
+
+```sh
+$ git pull
+$ git fetch --all
+```
+
+Before you can start please export an `GITHUB_AUTH` token into your environment in order to allow the executing script to fetch data about pull requests and set proper labels. Go to your [personal access token](https://github.com/settings/tokens) settings page and generate such token with only having the `public_repo` field enabled. Then export it into your environment and run the backport script. It fetches all commits connected with PRs that are labeled with `backport-requested` and cherry-picks them into the maintainance branch. Via an interactive console you can get the chance to review the PR again and whether you want to backport it or not. To start the process, just execute:
+
+```sh
+$ npm run backport
+```
+
+If during the process a cherry-pick fails you can always abort and manually troubleshoot. If you are not able to resolve the problem, create an issue in the repo and include the author of that PR. A successful backport of two PRs will look like this:
+
+```
+$ npm run backport
+
+> webdriverio-monorepo@ backport /path/to/webdriverio/webdriverio
+> node ./scripts/backport.js
+
+? You want to backport "Backporting Test PR" by christian-bromann?
+(See PR https://github.com/webdriverio/webdriverio/pull/4890) Yes
+Backporting sha 264b7bc49dfc3fe8f1ed8b58d681ce562aaf1544 from v6 to v5
+[cb-backport-process e47c5527] Backporting Test PR (#4890)
+ Author: Christian Bromann <mail@christian-bromann.com>
+ Date: Mon Dec 16 14:54:02 2019 +0100
+ 1 file changed, 2 insertions(+)
+? You want to backport "Second backport test" by christian-bromann?
+(See PR https://github.com/webdriverio/webdriverio/pull/4891) Yes
+Backporting sha 77dc52fdb86c51242b92f299998d2904004cb347 from v6 to v5
+[cb-backport-process 35a3ad41] Second backport test (#4891)
+ Author: Christian Bromann <mail@christian-bromann.com>
+ Date: Mon Dec 16 16:01:46 2019 +0100
+ 1 file changed, 2 deletions(-)
+
+Successfully backported 2 PRs 👏!
+Please now push them to master and make a new v5.x release!
+```
+
+You can always reach out to the `webdriverio/ProjectCommitters` channel on Gitter for questions.
+
 ## Commit Messages Convention

 In order to better identify which changes have been made to which package please add the package name in front of every commit, e.g.:
--- a/package-lock.json
+++ b/package-lock.json
@ -2736,9 +2736,9 @@
      }
    },
    "@octokit/rest": {
-      "version": "16.35.0",
-      "resolved": "https://registry.npmjs.org/@octokit/rest/-/rest-16.35.0.tgz",
-      "integrity": "sha512-9ShFqYWo0CLoGYhA1FdtdykJuMzS/9H6vSbbQWDX4pWr4p9v+15MsH/wpd/3fIU+tSxylaNO48+PIHqOkBRx3w==",
+      "version": "16.35.2",
+      "resolved": "https://registry.npmjs.org/@octokit/rest/-/rest-16.35.2.tgz",
+      "integrity": "sha512-iijaNZpn9hBpUdh8YdXqNiWazmq4R1vCUsmxpBB0kCQ0asHZpCx+HNs22eiHuwYKRhO31ZSAGBJLi0c+3XHaKQ==",
      "dev": true,
      "requires": {
        "@octokit/request": "^5.2.0",
--- a/package.json
+++ b/package.json
@ -3,6 +3,7 @@
  "private": true,
  "scripts": {
    "create": "node ./scripts/generateSubPackage",
+    "backport": "node ./scripts/backport.js",
    "bootstrap-full": "npm run clean && lerna bootstrap --no-ci && npm run link",
    "bootstrap": "run-p clean:* && lerna bootstrap --force-local && npm run link",
    "build-full": "lerna run --parallel build",
@ -62,6 +63,7 @@
    "@babel/plugin-syntax-export-default-from": "^7.2.0",
    "@babel/preset-env": "^7.6.2",
    "@babel/register": "^7.6.2",
+    "@octokit/rest": "^16.35.2",
    "@types/jest": "^24.0.18",
    "aws-sdk": "^2.539.0",
    "babel-core": "^6.26.3",
--- a/scripts/backport.js
+++ b/scripts/backport.js
@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+const Octokit = require('@octokit/rest')
+const inquirer = require('inquirer')
+const shell = require('shelljs')
+
+const activeLTSVersion = 'v6'
+const maintenanceLTSVersion = 'v5'
+
+/**
+ * check if `GITHUB_AUTH` environment variable is set to interact with GitHub API
+ */
+if (!process.env.GITHUB_AUTH) {
+    throw new Error(
+        'Please export a "GITHUB_AUTH" access token to generate the changelog.\n' +
+        'See also https://github.com/webdriverio/webdriverio/blob/master/CONTRIBUTING.md#release-new-version'
+    )
+}
+
+/**
+ * check if user is in right branch
+ */
+const { stdout: branch } = shell.exec('git rev-parse --abbrev-ref HEAD', { silent: true })
+if (branch !== maintenanceLTSVersion) {
+    throw new Error(
+        'In order to start backport process witch to the maintenance LTS branch via:\n' +
+        `$ git checkout ${maintenanceLTSVersion}`
+    )
+}
+
+function getPrompt (pr) {
+    return [{
+        name: 'toBackport',
+        type: 'confirm',
+        default: true,
+        message: `You want to backport "${pr.title}" by ${pr.user.login}?\n(See PR ${pr.html_url})`
+    }, {
+        name: 'exit',
+        type: 'confirm',
+        default: false,
+        message: 'Exit process?',
+        when: ({ toBackport }) => !toBackport
+    }]
+}
+
+const api = new Octokit({ auth: process.env.GITHUB_AUTH })
+
+/* eslint-disable no-console */
+;(async () => {
+    let backportedPRs = 0
+
+    const prs = await api.pulls.list({
+        owner: 'webdriverio',
+        repo: 'webdriverio',
+        state: 'closed',
+        sort: 'created',
+        direction: 'desc'
+    })
+    const prsToBackport = prs.data.filter(
+        (pr) => pr.labels.find(
+            (label) => label.name === 'backport-requested')).reverse()
+
+    if (prsToBackport.length === 0) {
+        console.log('Nothing to backport!')
+        return backportedPRs
+    }
+
+    for (const prToBackport of prsToBackport) {
+        const { toBackport, exit } = await inquirer.prompt(getPrompt(prToBackport))
+
+        if (exit) {
+            return backportedPRs
+        }
+
+        if (!toBackport) {
+            continue
+        }
+
+        console.log(`Backporting sha ${prToBackport.merge_commit_sha} from ${activeLTSVersion} to ${maintenanceLTSVersion}`)
+        const cherryPickResult = shell.exec(`git cherry-pick ${prToBackport.merge_commit_sha}`)
+
+        /**
+         * handle failing cherry-pick
+         */
+        if (cherryPickResult.stderr) {
+            const { exit } = await inquirer.prompt([{
+                name: 'exit',
+                type: 'confirm',
+                default: true,
+                message: 'Oh oh! Something failed with backporting, do you want to exit to check that?'
+            }])
+
+            if (exit) {
+                return backportedPRs
+            }
+
+            console.log('Ignoring error, continuing backporting...')
+            continue
+        }
+
+        /**
+         * switch labels
+         */
+        await api.issues.removeLabel({
+            owner: 'webdriverio',
+            repo: 'webdriverio',
+            issue_number: prToBackport.number,
+            name: 'backport-requested'
+        })
+        await api.issues.addLabels({
+            owner: 'webdriverio',
+            repo: 'webdriverio',
+            issue_number: prToBackport.number,
+            labels: ['backported']
+        })
+
+        ++backportedPRs
+    }
+
+    return backportedPRs
+})().then(
+    (amount) => console.log(amount
+        ? (
+            `\nSuccessfully backported ${amount} PRs 👏!\n` +
+            `Please now push them to master and make a new ${maintenanceLTSVersion}.x release!`
+        )
+        : 'Bye!'
+    ),
+    (err) => console.error(`Error backporting: ${err.stack}`)
+)