Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(doc): update RELEASING.md #14490

Merged
merged 5 commits into from
Mar 18, 2024
Merged

chore(doc): update RELEASING.md #14490

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
da2a622
chore(doc): start updating realeasing
y3rsh Feb 13, 2024
29f4a8b
backup
y3rsh Feb 21, 2024
be47e27
fix(docs): update instructions
y3rsh Mar 15, 2024
004958d
fix(docs): update instructions even more
y3rsh Mar 15, 2024
5e1a4c9
fix(docs): playing nice with prettier
y3rsh Mar 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
221 changes: 106 additions & 115 deletions RELEASING.md
View file
Open in desktop
y3rsh marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -1,197 +1,188 @@
# Releasing Software (for Opentrons developers)

Below you will find instructions for release processes for projects within our monorepo. The main goal of our process is to
neatly document any changes that may happen during QA, such as bug fixes, and separate production concerns from our development branch.
Below you will find instructions for the release processes for projects within this monorepo.

## Releasing Robot Software Stacks

The app and API projects are currently versioned together to ensure interoperability.
### Overview

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.
The robot release process has 3 main outputs:

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.
- Opentrons App
- OT-2 system package
- Flex system package

```shell
git checkout edge
git pull
git checkout -b release_${version}
git push --set-upstream origin release_${version}
```

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.
The robot software stack is composed of the following repositories:

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.

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 checkout release_${version}
git pull
git tag -a v${alphaVersion} -m 'chore(release): ${alphaVersion}'
```
- [opentrons]("https://github.com/Opentrons/opentrons") (this repository)
- [opentrons_modules]("https://github.com/Opentrons/opentrons-modules") (module firmware)
- [oe_core]("https://github.com/Opentrons/oe-core") (Flex OS)
- [ot3_firmware]("https://github.com/Opentrons/ot3-firmware") (Flex firmware)
- [buildroot]("https://github.com/Opentrons/buildroot") (OT-2 OS)

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.
```mermaid
flowchart LR
subgraph Shared ["Shared Repositories"]
opentrons["Opentrons/opentrons" ]
opentrons_modules["Opentrons/opentrons-modules" ]
end

```shell
git push origin v${alphaVersion}
```
subgraph Flex ["Flex Only"]
oe_core["Opentrons/oe-core"]
ot3_firmware["Opentrons/ot3-firmware" ]
end

Changelogs for the release are automatically generated when the tag is pushed and sent to the release page in github.
subgraph OT2 ["OT-2 Only"]
buildroot["Opentrons/buildroot" ]
end

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.
OT2Build["OT-2 System Package"]
opentrons --> OT2Build
buildroot --> OT2Build

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):
App["Opentrons App"]
opentrons --> App

```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
FlexBuild["Flex System Package"]
opentrons --> FlexBuild
oe_core --> FlexBuild
ot3_firmware --> FlexBuild
opentrons_modules --> OT2Build
opentrons_modules --> FlexBuild
```

git merge --ff-only release_${version}
git push origin release
```
These are all versioned and released together. These assets are produced in 2 possible channels:

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:
- Release (External facing releases - stable, beta, alpha)
- Internal Release (Internal facing releases - stable, beta, alpha)

```shell
git tag -a v${version} -m 'chore(release): ${version}'
git show v${version}
```
> [!TIP] > `git config remote.origin.tagOpt --tags` ensures that when you fetch and pull, you get all the tags from the origin remote.

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.
### Steps to release the changes in `edge`

Once the tag looks good, you can push it:
1. Checkout `edge` and make a chore release branch, without any new changes. The branch name should match `chore_release-${version}`.

```shell
git push origin v${version}
git switch edge
git pull
git switch -c chore_release-${version}
git push --set-upstream origin chore_release-${version}
```

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.

9. Ensure all deploy jobs succeeded:

- The Opentrons App should be prompting people to update to the new version.
- https://pypi.org/project/opentrons/ should be showing the new version.

10. Release the Python Protocol API docs for this version (see below under Releasing Web Projects).

11. Update the download links on https://opentrons.com/ot-app/. That page is defined in an Opentrons private repository.
2. Open a PR targeting `release` from `chore_release-${version}`; this should contain all the changes that were in `edge` and not yet in `release`. This PR will not be merged in GitHub. Apply the `DO NOT MERGE` label. When we are ready, approval and passing checks on this PR allows the bypass of the branch protection on `release` that prevents direct pushes. Step 8 will resolve this PR.

12. 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`:
3. Evaluate changes on our dependent repositories. If there have been changes to `opentrons-modules`, `oe-core`, `ot3-firmware`, or `buildroot`, ensure that the changes are in the correct branches. Tags will need to be pushed to repositories with changes. Further exact tagging instructions for each of the repositories are TODO.

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

13. 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.
4. Check out and pull `chore_release-${version}` locally. Create a tag for a new alpha version. The alpha versions end with an `-alpha.N` prerelease tag, where `N` increments by 1 from 0 over the course of the QA process. You don't need a PR or a commit to create a new version. Pushing tags in the formats prescribed here are the triggers of the release process. Let's call the alpha version you're about to create `${alphaVersion}`:

## 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 be `hotfix_${version}` to make it clear this is a hotfix.
> [!IMPORTANT]
> Use annotated tag (`-a`) with a message (`-m`) for all tags.

```shell
git checkout release
git switch chore_release-${version}
git pull
git checkout -b hotfix_${version}
git push --set-upstream origin hotfix_${version}
git tag -a v${alphaVersion} -m 'chore(release): ${alphaVersion}
```

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 by creating and pushing a tag. Let's call the new alpha version `${alphaVersion}`:
5. Review the tag with `git log v${alphaVersion} --oneline -n10`. 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. Changelogs for the release are automatically generated when the tag is pushed and sent to the release page in github.

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

6. Inspect the created tag and then push it:
6. Run QA on this release. If issues are found, create PRs targeting `chore_release-${version}`. To create a new alpha releases, repeat steps 4-6.

```shell
git show v${alphaVersion}
```
7. Once QA is complete, do a final check that the release notes are complete and proof-read.

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.
8. We are ready to `merge -ff-only` the `chore_release-${version}` into `release`.

```shell
git push v${alphaVersion}
```
> [!CAUTION]
>
> - Do **NOT** squash or rebase
> - Do **NOT** yet push a tag

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.

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):
This should be done from your local command line. Here we make use of the PR in step 2 to bypass the branch protection on `release`. The PR checks must be passing and the PR must have approval:

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

9. Tag the release with its full target version, which we'll call `${version}` since it's no longer an alpha:
9. 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:

> [!IMPORTANT]
> Use annotated tag (`-a`) with a message (`-m`) for all tags.

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

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.
The `git log` 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, push it:
Once the tag looks good, you can push it. 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.

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

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

10. Ensure all deploy jobs succeeded:
10. Ensure package deployments succeed by validating the version in our release dockets. The examples below are for the release channel. Internal Release channel looks a little different but are similar and documented elsewhere.

- The Opentrons App should be prompting people to update to the new version.
- https://pypi.org/project/opentrons/ should be showing the new version.
- Flex <https://builds.opentrons.com/ot3-oe/releases.json>
- OT-2 <https://builds.opentrons.com/ot2-br/releases.json>
- App Stable
- <https://builds.opentrons.com/app/latest.yml> Windows
- <https://builds.opentrons.com/app/latest-mac.yml>
- <https://builds.opentrons.com/app/latest-linux.yml>
- App Alpha
- <https://builds.opentrons.com/app/alpha.yml> Windows
- <https://builds.opentrons.com/app/alpha-mac.yml>
- <https://builds.opentrons.com/app/alpha-linux.yml>
- Python `opentrons` package <https://pypi.org/project/opentrons>
- Python `opentrons-shared-data` package <https://pypi.org/project/opentrons-shared-data>
- The Opentrons App should be prompting people to update to the new version given their current channel.

11. Update the download links on https://opentrons.com/ot-app/. That page is defined in an Opentrons private repository.
11. Release the Python Protocol API docs for this version (see below under Releasing Web Projects).

12. Release the Python Protocol API docs for this version (see below under Releasing Web Projects)

13. 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`:
12. Open a PR of `release` into `edge`. Give the PR a name like `chore(release): Merge changes from ${version} into edge`. Once it passes and has approval, on the command line merge it into `edge`:

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

14. 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.
13. 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.

## Releasing Robot Software Stack Isolated changes

If critical bugfixes or isolated features need to be released, the process is the same as above, but the `chore_release-${version}` branch is not created from `edge`. We would likely base the `chore_release-${version}` branch on `release` then create bug fix PRs targeting `chore_release-${version}`. Or we might cherry pick in commits and/or merge in a feature branch to `chore_release-${version}`.

### tag usage

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:
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.

> [!IMPORTANT]
> Use annotated tag (`-a`) with a message (`-m`) for all tags.

#### Tags look like this:

```shell
${projectPrefix}${projectVersion}
```

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

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]`.
##### Examples

- the tag for 6.2.1-alpha.3 of the robot stack is `v6.2.1-alpha.3`
- the tag for 0.1.2-beta.1 of an internal release or robot stack is `[email protected]`
- the tag for 4.0.0 of protocol designer 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.

Expand Down
Loading