Skip to content

Commit

Permalink
Merge branch 'edge' into g-code-214
Browse files Browse the repository at this point in the history 
* edge:
  refactor(protocol-engine): Shorten error docstrings (#12230)
  chore(app): update electron-builder version from v24 alpha to v24 (#12233)
  chore(app): add new icons for ODD hi-fi (#12231)
  docs: more release docs (#12226)
  fix(app, odd): check isOnDevice true instead of if it is null (#12228)
  docs: remove references to make bump in releasing (#12222)
  refactor(app): scroll to current split from jump to tick, qol tweaks to run preview (#12218)
  fix(app): rewire cli and jupyter snippets to offsets modals  (#12180)
  feat(app): handle non-deterministic protocols (#12173)
  • Loading branch information
@y3rsh
y3rsh committed Mar 6, 2023
2 parents 1fd37a0 + 710c8fe commit f7210c0
Show file tree
Hide file tree
Showing 31 changed files with 1,030 additions and 811 deletions.
5 changes: 0 additions & 5 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -252,8 +252,3 @@ circular-dependencies-js:
yarn madge $(and $(CI),--no-spinner --no-color) --circular step-generation/src/index.ts
yarn madge $(and $(CI),--no-spinner --no-color) --circular labware-library/src/index.tsx
yarn madge $(and $(CI),--no-spinner --no-color) --circular app/src/index.tsx

.PHONY: bump
bump:
@echo "Bumping versions"
yarn lerna version $(or $(version),prerelease)
163 changes: 76 additions & 87 deletions RELEASING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ neatly document any changes that may happen during QA, such as bug fixes, and se
Our release process is still a work-in-progress. The app and API projects are currently versioned together to ensure interoperability.

1. Ensure you have a release created in GitHub for the robot stack you're releasing - buildroot for ot-2, oe-core for ot-3 - with all the changes you want in this release, if any. If there are no system changes, you don't have to create a new release; the last tag in the system repo is used for release builds.
2. Checkout `edge` and make a release branch, without any new changes. The branch name should match `release_*` to make `make bump` usage easier and make it clear this is a release.
2. Checkout `edge` and make a release branch, without any new changes. The branch name should match `release_*` to make it clear this is a release.

```shell
git checkout edge
Expand All @@ -17,61 +17,74 @@ git checkout -b release_${version}
git push --set-upstream origin release_${version}
```

3. Open a PR into `release` for your empty release branch.
4. Seek input on the user-facing release notes at `app-shell/build/release-notes.md` to add the new notes for the app and user-facing release notes at `api/release-notes.md` to add the new notes for the robot software. These changes should get wordsmithing approval and use a `chore` merge commit. This can happen in parallel, but should be done before the alpha process concludes.
3. Open a PR into `release` for your release branch; this should contain all the changes that were in edge and not yet release. This PR will stick around for the duration of the release process, as QA-discovered bugs will have their fixes merged to this PR.

5. Create a tag using `make bump` for the new version. See the notes on [`make bump` usage](#make-bump-usage) below. Since this is entering qa, you'll want to bump the version to the target release version with an `-alpha.0` prerelease tag.
Part of what should happen in this branch is soliciting input and changes for the user-facing release notes at `app-shell/build/release-notes.md` for the app and `api/release-notes.md` for the robot software. Any changes should be done in a PR just like a QA bug. You should have final approval before the alpha process concludes.

6. Review the tag with `git show ${project}@${version}` (or `git show v${version}` for the robot-stack project). If it points to the commit you meant, push the tag - this starts the build process. This is a release candidate that will undergo QA.
4. Check out and pull your release branch locally and create a tag for a new alpha version (since this is in QA). The alpha version should end with an `-alpha.N` prerelease tag, where `N` goes from 0 up over the course of the QA process. You don't need a PR or a commit to create a new version; the presence of the tag is all that you need. Let's call the alpha version you're about to create `${alphaVersion}`:

```shell
git push origin ${project}@${version}
git checkout release_${version}
git pull
git tag -a v${alphaVersion} -m 'chore(release): ${alphaVersion}'
```

or
5. Review the tag with `git show v${alphaVersion}`. Double check that the commit displayed is the one you want - it should probably be the latest commit in your release branch, and you should double check that with the Github web UI. If the tag looks good, push it - this starts the build process. This is a release candidate that will undergo QA.

```shell
git push origin v${version}
git push origin v${alphaVersion}
```

Changelogs for the release are automatically generated when the tag is pushed and sent to the release page in github.

7. Run QA on this release. If issues are found, create PRs targeted on the release branch. To create new alpha releases, repeat steps 4-7.
6. Run QA on this release. If issues are found, create PRs targeted on the release branch. To create new alpha releases, repeat steps 4-6.

8. Once QA is a pass, do a NORMAL MERGE into `release`. Do NOT squash or rebase. This should be done from your local command line (and will succeed as long as the release PR is reviewed and status checks have passed):
7. Once QA is a pass, do a final check that the release notes are good and wordsmithed, and then do a NORMAL MERGE into `release`. Do NOT squash or rebase; do NOT yet push a tag. This should be done from your local command line (and will succeed as long as the release PR is reviewed and status checks have passed):

```shell
# note: make sure you have pulled the latest changes for branch
# release_${version} locally before merging into release
git checkout release_${version}
git pull
git checkout release
git pull

git merge --ff-only release_${version}
git push origin release
```

10. Run [`make bump`](#make-bump-usage) to tag the release and start release builds:
8. Make a tag for the release. This tag will have the actual target release version, no alpha prerelease tags involved. It should be the same as the `${version}` part of your release branch:

```shell
git tag -a v${version} -m 'chore(release): ${version}'
git show v${version}
```

The `git show` should reveal that the tag is on what was, pre-merge, the last commit of your release branch and is, post-merge, the last commit of `release`. You should double-check this with the github web UI.

Once the tag looks good, you can push it:

```shell
git push origin v${version}
```

The tag push will kick off release builds and create a release page where those builds and automatically generated in-depth changelogs will be posted.
The tag push will kick off release builds and deploy the results to customers. It will also create a release page where those builds and automatically generated in-depth changelogs will be posted.

11. Open a PR of `release` into `edge`. Give the PR a name like `chore(release): Merge changes from ${version} into edge`. Once it passes, on the command line merge it into `edge`:
9. Open a PR of `release` into `edge`. Give the PR a name like `chore(release): Merge changes from ${version} into edge`. Once it passes, on the command line merge it into `edge`:

```shell
git checkout edge
git pull
git merge --no-ff release
```

12. Use the PR title for the merge commit title. You can then `git push origin edge`, which will succeed as ong as the PR is approved and status checks pass.
13. Release the docs for this version (see below under Releasing Web Projects)
10. Use the PR title for the merge commit title. You can then `git push origin edge`, which will succeed as long as the PR is approved and status checks pass.
11. Release the docs for this version (see below under Releasing Web Projects)

## Releasing Robot Software Stack Hotfixes

1. Ensure you have a system release created in GitHub (buildroot for OT2, oe-core for OT3) with all the changes you want to see, if any. If there aren't any, you don't have to create a new release; by default, the last tag is used for release builds.
2. Checkout `release` and make a release branch, without any new changes. The branch name should match `hotfix_*` to make it clear this is a hotfix, and make `make bump` usage simpler.
2. Checkout `release` and make a release branch, without any new changes. The branch name should be `hotfix_${version}` to make it clear this is a hotfix.

```shell
git checkout release
Expand All @@ -82,113 +95,89 @@ git push --set-upstream origin hotfix_${version}

3. Target the hotfix PRs on this branch.
4. Wordsmith the release notes in `app-shell/build/release-notes.md` and `api/release-notes.md` in a PR that uses the `chore` commit type.
5. Once the fixes and release notes have been merged into the hotfix branch, bump to an alpha version to begin qa using [`make bump`](#make-bump-usage).
6. Inspect the created tag and then push it:
5. Once the fixes and release notes have been merged into the hotfix branch, bump to an alpha version to begin qa by creating and pushing a tag. Let's call the new alpha version `${alphaVersion}`:

```shell
git push ${tag}
git checkout hotfix_${version}
git pull
git tag -a v${alphaVersion} -m 'chore(release): ${alphaVersion}'
git show v${alphaVersion}
```

7. Once QA is a pass, do a NORMAL MERGE into `release`. Do NOT squash or rebase. This should be done from your local command line (and will succeed as long as the release PR is reviewed and status checks have passed):
6. Inspect the created tag and then push it:

```shell
# note: make sure you have pulled the latest changes for branch
# release_${version} locally before merging into release
git checkout release
git merge --ff-only release_${version}
git push origin release
git show v${alphaVersion}
```

8. Tag the release using [`make bump`](#make-bump-usage)

Pushing the tag will create release builds and a github release page with the in-depth changelogs.

9. Open a PR of `release` into `edge`. Give the PR a name like `chore(release): Merge changes from ${version} into edge`. Once it passes, on the command line merge it into `edge`:
The `git show` command should reveal that the tag points to the latest commit of the hotfix branch. You should verify this with the github web UI.

```shell
git checkout edge
git pull
git merge --no-ff release
git push v${alphaVersion}
```

10. Use the PR title for the merge commit title. You can then `git push origin edge`, which will succeed as long as the PR is approved and status checks pass.
11. Release the docs for this version (see below under Releasing Web Projects)

### tag usage
7. QA the release build. If there are problems discovered, do normal PR processes to merge the further changes into the hotfix branch. Once issues are fixed, repeat steps 5-7 with a new alpha version.

If you know the version (at this stage, it should be a new minor or patch version with an alpha tag) you can specify it with `version` and `project`, where `project` is one of our multi-application projects: `docs`, `robot-stack`, `labware-library`, `protocol-designer`, `ot3`:
8. Once QA is a pass, do a NORMAL MERGE into `release`. Do NOT squash or rebase. This should be done from your local command line (and will succeed as long as the release PR is reviewed and status checks have passed):

```shell
make bump project=${project} version=${version}
# note: make sure you have pulled the latest changes for branch
# release_${version} locally before merging into release
git checkout hotfix_${version}
git pull
git checkout release
git pull
git merge --ff-only release_${version}
git push origin release
```

i.e.

If not, you can follow the prompts:
9. Tag the release with its full target version, which we'll call `${version}` since it's no longer an alpha:

```shell
make bump
Enter the project (labware-library,docs,robot-stack,ot3,protocol-designer):
The current version of ${project} is ${current-version}
The next prerelease version of ${project} would be ${version}
The next release version of ${project} would be ${version}
Enter version exactly or bump type (prerelease,alpha,beta,candidate,release)
version:
git tag -a v${version} -m 'chore(release): ${version}'
git show v${version}
```

`make bump` runs `lerna version` (with git tag and push disabled) to bump all required files. You can pass options to lerna with the `version` environment variable. See the [lerna version docs][lerna-version] for available options. The most important options are:
The `git show` command should reveal that the tag points to the most recent commit of the `release` branch, which should be the most recent commit on the hotfix branch you just merged. You should verify this with the Github web UI.

- First positional argument: bump type _or_ explicit version
- Default: `prerelease`
- Valid bumps: `major`, `minor`, `patch`, `premajor`, `preminor`, `prepatch`, `prerelease`. Alpha versions should be created with `premajor`, `preminor`, `prepatch`, or `prerelease`. Releases should be `major`, `minor`, or `patch`.
- See [semver.inc][semver-inc] for keyword meanings
- `--preid` - Used to specify the pre-release identifier
- Default: `alpha`
- Valid: `alpha`, `beta`
- `--allow-branch` - Specifically allow a branch to be bumped
- By default, Lerna will only accept a bump on a branch named `release_*` or `hotfix_*`
Once the tag looks good, push it:

```shell
# by default, bump to next alpha prerelease:
# e.g. 3.0.0 -> 3.0.1-alpha.0
# e.g. 3.0.1-alpha.0 -> 3.0.1-alpha.1
make bump

# equivalent to above
make bump version="prerelease"
git push origin v${version}
```

# bump to a beta version, the standard practice for a new release
make bump version="prerelease --preid=beta"
Pushing the tag will create release builds and a github release page with the in-depth changelogs.

# prerelease minor version bump (e.g. 3.0.0 -> 3.1.0-alpha.0)
make bump version="preminor"
10. Open a PR of `release` into `edge`. Give the PR a name like `chore(release): Merge changes from ${version} into edge`. Once it passes, on the command line merge it into `edge`:

# minor version bump (e.g. 3.0.0-alpha.0 -> 3.1.0)
make bump version="minor"
```shell
git checkout edge
git pull
git merge --no-ff release
```

# bump to an explicit version
make bump version="42.0.0"
11. Use the PR title for the merge commit title. You can then `git push origin edge`, which will succeed as long as the PR is approved and status checks pass.
12. Release the docs for this version (see below under Releasing Web Projects)

# bump a patch version, e.g. for a hotfix
make bump version="patch --allow-branch hotfix_*"
```
### tag usage

We use [lerna][], a monorepo management tool, to work with our various projects. You can use lerna to do things like see which projects have changed since the last release, or run a command in every project directory. To run a one-off lerna command, use:
We specify the version of a release artifact through a specifically-formatted git tag. We consider our monorepo to support several projects: robot stack, ot3, protocol-designer, etc. Tags look like this:

```shell
# use yarn run to run devDependency CLI tools like lerna
yarn run lerna [opts]
${projectPrefix}${projectVersion}
```

## Releasing Web Projects
`${projectPrefix}` is the project name plus `@` for everything but robot stack, where it is `v`.

The following web projects are versioned and released independently from the app and API:
For instance, the tag for 6.2.1-alpha.3 of the robot stack is `v6.2.1-alpha.3`.
The tag for 4.0.0 of protocol designer is `[email protected]`.
The tag for 0.1.2-beta.1 of ot3 is `[email protected]`.

Versions follow [semver.inc][semver-inc]. QA is done on alpha builds, and only alpha tags should be pushed until you're ready to release the project.

## Releasing Web Projects

- `protocol-designer`
- designer.opentrons.com
- `labware-library`
- labware.opentrons.com
- API documentation
- docs.opentrons.com
While our web projects also take their versions from appropriately-prefixed git tags, they will not be automatically deployed.

See [scripts/deploy/README.md](./scripts/deploy/README.md) for the release process of these projects.
Loading

0 comments on commit f7210c0

Please sign in to comment.