From 7bf12dbfbb072b961969e4e247179af7af031bd9 Mon Sep 17 00:00:00 2001 From: Chris Breiding Date: Thu, 23 Jul 2020 03:27:03 -0400 Subject: [PATCH] Make improvements to deploy doc (#8057) --- DEPLOY.md | 124 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 71 insertions(+), 53 deletions(-) diff --git a/DEPLOY.md b/DEPLOY.md index ce44fc4fe8..52537c0d8c 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -1,7 +1,6 @@ # Deployment -Anyone can build the binary and NPM package, but you can only deploy the Cypress application -and publish the NPM module `cypress` if you are a member of the `cypress` NPM organization. +Anyone can build the binary and NPM package, but you can only deploy the Cypress application and publish the NPM module `cypress` if you are a member of the `cypress` NPM organization. > :information_source: See the [publishing](#publishing) section for how to build, test and publish a new official version of the binary and `cypress` NPM package. @@ -35,6 +34,32 @@ You can build the Cypress binary locally by running `yarn binary-build`. You can ## Publishing +### Prerequisites + +- Ensure you have the following permissions set up: + - An AWS account with permission to create AWS access keys for the Cypress CDN. + - Permissions for your npm account to publish the `cypress` package. + - Permissions to modify environment variables for `cypress` on CircleCI and AppVeyor. + - Permissions to update releases in ZenHub. + +- Set up the following environment variables: + - Cypress AWS access key and secret in `aws_credentials_json`, which looks like this: + ```text + aws_credentials_json={"bucket":"cdn.cypress.io","folder":"desktop","key":"...","secret":"..."} + ``` + - A [GitHub token](https://github.com/settings/tokens), a [CircleCI token](https://circleci.com/account/api), + and a `cypress-io` account-specific [AppVeyor token](https://ci.appveyor.com/api-keys) in `ci_json`: + ```text + ci_json={"githubToken":"...","circleToken":"...","appVeyorToken":"..."} + ``` + - You'll also need to put the GitHub token under its own variable and get a [ZenHub API token](https://app.zenhub.com/dashboard/tokens) for the `release-automations` step. + ```text + GITHUB_TOKEN="..." + ZENHUB_API_TOKEN="..." + ``` + - The `cypress-bot` GitHub app credentials are also needed. Ask another team member who has done a deploy for those. + - Tip: Use [as-a](https://github.com/bahmutov/as-a) to manage environment variables for different situations. + ### Before Publishing a New Version In order to publish a new `cypress` package to the NPM registry, we must build and test it across multiple platforms and test projects. This makes publishing *directly* into the NPM registry impossible. Instead, we have CI set up to do the following on every commit to `develop`: @@ -60,35 +85,14 @@ Once the `develop` branch for all test projects are reliably passing with the ne In the following instructions, "X.Y.Z" is used to denote the version of Cypress being published. -0. Make sure that if there is a new [`cypress-example-kitchensink`](https://github.com/cypress-io/cypress-example-kitchensink/releases) version, the corresponding dependency in [`packages/example`](./packages/example) has been updated to that new version. -1. Make sure you have the correct permissions set up before proceeding: - - An AWS account with permission to create AWS access keys for the Cypress CDN. - - Permissions for your npm account to publish the `cypress` package. - - Permissions to modify environment variables for `cypress` on CircleCI and AppVeyor. - - Permissions to update releases in ZenHub. -2. Make sure that you have the correct environment variables set up before proceeding: - - Cypress AWS access key and secret in `aws_credentials_json`, which looks like this: - ```text - aws_credentials_json={"bucket":"cdn.cypress.io","folder":"desktop","key":"...","secret":"..."} - ``` - - A [GitHub token](https://github.com/settings/tokens), a [CircleCI token](https://circleci.com/account/api), - and a `cypress-io` account-specific [AppVeyor token](https://ci.appveyor.com/api-keys) in `ci_json`: - ```text - ci_json={"githubToken":"...","circleToken":"...","appVeyorToken":"..."} - ``` - - You'll also need to put the GitHub token under its own variable and get a [ZenHub API token](https://app.zenhub.com/dashboard/tokens) for the `release-automations` step. - ```text - GITHUB_TOKEN="..." - ZENHUB_API_TOKEN="..." - ``` - - The `cypress-bot` GitHub app credentials are also needed. Ask another team member who has done a deploy for those. - - Tip: Use [as-a](https://github.com/bahmutov/as-a) to manage environment variables for different situations. -3. Use the `move-binaries` script to move the binaries for `` from `beta` to the `desktop` folder - for `` +1. If there is a new [`cypress-example-kitchensink`](https://github.com/cypress-io/cypress-example-kitchensink/releases) version, update the corresponding dependency in [`packages/example`](./packages/example) to that new version. + +2. Use the `move-binaries` script to move the binaries for `` from `beta` to the `desktop` folder for `` ```shell yarn move-binaries --sha --version ``` -4. Publish the new NPM package under the `dev` tag, using your personal NPM account. + +3. Publish the new NPM package under the `dev` tag, using your personal NPM account. - To find the link to the package file `cypress.tgz`: 1. In GitHub, go to the latest commit (the one whose sha you used in the last step). ![commit-link](https://user-images.githubusercontent.com/1157043/80608728-33fe6100-8a05-11ea-8b53-375303757b67.png) @@ -98,12 +102,14 @@ In the following instructions, "X.Y.Z" is used to denote the version of Cypress ```shell npm publish https://cdn.../npm/X.Y.Z//cypress.tgz --tag dev ``` -5. Double-check that the new version has been published under the `dev` tag using `npm info cypress` or [available-versions](https://github.com/bahmutov/available-versions). `latest` should still point to the previous version. Example output: + +4. Double-check that the new version has been published under the `dev` tag using `npm info cypress` or [available-versions](https://github.com/bahmutov/available-versions). `latest` should still point to the previous version. Example output: ```shell dist-tags: dev: 3.4.0 latest: 3.3.2 ``` -6. Test `cypress@X.Y.Z` to make sure everything is working. + +5. Test `cypress@X.Y.Z` to make sure everything is working. - Install the new version: `npm install -g cypress@X.Y.Z` - Run a quick, manual smoke test: - `cypress open` @@ -114,7 +120,8 @@ In the following instructions, "X.Y.Z" is used to denote the version of Cypress node scripts/test-other-projects.js --npm cypress@X.Y.Z --binary X.Y.Z ``` - Test the new version of Cypress against the Cypress dashboard repo. -7. Deploy the release-specific documentation and changelog in [cypress-documentation](https://github.com/cypress-io/cypress-documentation). + +6. Deploy the release-specific documentation and changelog in [cypress-documentation](https://github.com/cypress-io/cypress-documentation). - If there is not already a release-specific PR open, create one. You can use [`release-automations`](https://github.com/cypress-io/release-automations)'s `issues-in-release` tool to generate a starting point for the changelog, based off of ZenHub: ``` cd packages/issues-in-release @@ -123,37 +130,44 @@ In the following instructions, "X.Y.Z" is used to denote the version of Cypress - Ensure the changelog is up-to-date and has the correct date. - Merge any release-specific documentation changes into the main release PR. - Merging this PR into `develop` will deploy to `docs-staging` and then a PR will be automatically created against `master`. It will be automatically merged after it passes and will deploy to production. -8. Make the new NPM version the "latest" version by updating the dist-tag `latest` to point to the new version: + +7. Make the new NPM version the "latest" version by updating the dist-tag `latest` to point to the new version: ```shell npm dist-tag add cypress@X.Y.Z ``` -9. Run `binary-release` to update the [download server's manifest](https://download.cypress.io/desktop.json) and set the next CI version: + +8. Run `binary-release` to update the [download server's manifest](https://download.cypress.io/desktop.json) and set the next CI version: ```shell yarn run binary-release --version X.Y.Z ``` - > Note: Currently, there is an [issue setting the next CI version](https://github.com/cypress-io/cypress/issues/7176) that will cause this command to fail after setting the download manifest. You will need to manually update NEXT_DEV_VERSION by logging in to CircleCI and AppVeyor. -10. If needed, push out any updated changes to the links manifest to [`on.cypress.io`](https://github.com/cypress-io/cypress-services/tree/develop/packages/on). -11. If needed, deploy the updated [`cypress-example-kitchensink`][cypress-example-kitchensink] to `example.cypress.io` by following [these instructions under "Deployment"](./packages/example/README.md). -12. Update the releases in [ZenHub](https://app.zenhub.com/workspaces/test-runner-5c3ea3baeb1e75374f7b0708/reports/release): + > Note: Currently, there is an [issue setting the next CI version](https://github.com/cypress-io/cypress/issues/7176) that will cause this command to fail after setting the download manifest. You will need to manually update NEXT_DEV_VERSION by logging in to CircleCI and AppVeyor. This is noted in Step 16 below. + +9. If needed, push out any updated changes to the links manifest to [`on.cypress.io`](https://github.com/cypress-io/cypress-services/tree/develop/packages/on). + +10. If needed, deploy the updated [`cypress-example-kitchensink`][cypress-example-kitchensink] to `example.cypress.io` by following [these instructions under "Deployment"](./packages/example/README.md). + +11. Update the releases in [ZenHub](https://app.zenhub.com/workspaces/test-runner-5c3ea3baeb1e75374f7b0708/reports/release): - Close the current release in ZenHub. - Create a new patch release (and a new minor release, if this is a minor release) in ZenHub, and schedule them both to be completed 2 weeks from the current date. - Move all issues that are still open from the current release to the appropriate future release. -13. Bump `version` in [`package.json`](package.json), commit it to `develop`, and tag it with version: - ```shell - # commit and tag at the same time - git commit -a vX.Y.Z -m "release X.Y.Z [skip ci]" - # OR if you don't tag it with the commit, you can tag it after - git commit -m "release X.Y.Z [skip ci]" - git log --pretty=oneline # copy sha of the previous commit - git tag -a vX.Y.Z - ``` -14. Push the tag up: +12. Bump `version` in [`package.json`](package.json), commit it to `develop`, tag it with the version, and push the tag up: ```shell + git commit -am "release X.Y.Z [skip ci]" + git log --pretty=oneline + # copy sha of the previous commit + git tag -a vX.Y.Z git push origin vX.Y.Z ``` -15. Merge `develop` into `master` and push that branch up. -16. Inside of [cypress-io/release-automations][release-automations]: +13. Merge `develop` into `master` and push both branches up. + ```shell + git push origin develop + git checkout master + git merge develop + git push origin master + ``` + +14. Inside of [cypress-io/release-automations][release-automations]: - Publish GitHub release to [cypress-io/cypress/releases](https://github.com/cypress-io/cypress/releases) using package `set-releases`: ```shell cd packages/set-releases && npm run release-log -- --version X.Y.Z @@ -162,9 +176,12 @@ In the following instructions, "X.Y.Z" is used to denote the version of Cypress ```shell cd packages/issues-in-release && npm run do:comment -- --release X.Y.Z ``` -17. Publish a new docker image in [`cypress-docker-images`](https://github.com/cypress-io/cypress-docker-images) under `included` for the new cypress version. -18. Decide on the next version that we will work on. For example, if we have just released `3.7.0` we probably will work on `3.7.1` next. Set it on [CI machines](#set-next-version-on-cis). -19. Update example projects to the new version. For most projects, you can go to the Renovate dependency issue and check the box next to `Update dependency cypress to X.Y.Z`. It will automatically create a PR. Once it passes, you can merge it. Try updating at least the following projects: + +15. Publish a new docker image in [`cypress-docker-images`](https://github.com/cypress-io/cypress-docker-images) under `included` for the new cypress version. + +16. Decide on the next version that we will work on. For example, if we have just released `3.7.0` we probably will work on `3.7.1` next. Set it on [CI machines](#set-next-version-on-cis). + +17. Update example projects to the new version. For most projects, you can go to the Renovate dependency issue and check the box next to `Update dependency cypress to X.Y.Z`. It will automatically create a PR. Once it passes, you can merge it. Try updating at least the following projects: - [cypress-example-todomvc](https://github.com/cypress-io/cypress-example-todomvc/issues/99) - [cypress-example-todomvc-redux](https://github.com/cypress-io/cypress-example-todomvc-redux/issues/1) - [cypress-example-realworld](https://github.com/cypress-io/cypress-example-realworld/issues/2) @@ -175,7 +192,8 @@ In the following instructions, "X.Y.Z" is used to denote the version of Cypress - [cypress-example-piechopper](https://github.com/cypress-io/cypress-example-piechopper/issues/75) - [cypress-documentation](https://github.com/cypress-io/cypress-documentation/issues/1313) - [cypress-example-docker-compose](https://github.com/cypress-io/cypress-example-docker-compose) - Doesn't have a Renovate issue, but will auto-create and auto-merge non-major Cypress updates as long as the tests pass. -20. Check if any test or example repositories have a branch for testing the features or fixes from the newly published version `x.y.z`. The branch should also be named `x.y.z`. Check all `cypress-test-*` and `cypress-example-*` repositories, and if there is a branch named `x.y.z`, merge it into `master`. + +18. Check if any test or example repositories have a branch for testing the features or fixes from the newly published version `x.y.z`. The branch should also be named `x.y.z`. Check all `cypress-test-*` and `cypress-example-*` repositories, and if there is a branch named `x.y.z`, merge it into `master`. **Test Repos**