mirror/cypress
1
0
Fork 0
mirror of https://github.com/cypress-io/cypress.git synced 2026-01-23 23:49:05 -06:00
Code Issues Packages Projects Releases Wiki Activity

Make improvements to deploy doc (#8057)

Browse Source
This commit is contained in:
Chris Breiding
2020-07-23 03:27:03 -04:00
committed by GitHub
parent a1c562f29f
commit 7bf12dbfbb
1 changed files with 71 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
DEPLOY.md
View File

@@ -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 `<commit sha>` from `beta` to the `desktop` folder
for `<new target version>`
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 `<commit sha>` from `beta` to the `desktop` folder for `<new target version>`
```shell
yarn move-binaries --sha <commit sha> --version <new target 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/<long sha>/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 <sha>
```
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 <sha>
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**