Skip to content

Commit 5d74255

Browse files
y3rshy3rsh
authored
chore(doc): update RELEASING.md (#14490)
## [RDEVOPS-43](https://opentrons.atlassian.net/browse/RDEVOPS-43) Use the rich diff to see the rendered output 😊 [RDEVOPS-43]: https://opentrons.atlassian.net/browse/RDEVOPS-43?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
1 parent 6dee683 commit 5d74255

File tree

1 file changed

+109
-124
lines changed

1 file changed

+109
-124
lines changed

‎RELEASING.md

Lines changed: 109 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -1,197 +1,182 @@
11
# Releasing Software (for Opentrons developers)
22

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

65
## Releasing Robot Software Stacks
76

8-
The app and API projects are currently versioned together to ensure interoperability.
7+
### Overview
98

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

12-
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.
11+
- Opentrons App
12+
- OT-2 system package
13+
- Flex system package
1314

14-
```shell
15-
git checkout edge
16-
git pull
17-
git checkout -b release_${version}
18-
git push --set-upstream origin release_${version}
19-
```
15+
The robot software stack is composed of the following repositories:
2016

21-
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.
17+
- [opentrons]("https://github.com/Opentrons/opentrons") (this repository)
18+
- [opentrons_modules]("https://github.com/Opentrons/opentrons-modules") (module firmware)
19+
- [oe_core]("https://github.com/Opentrons/oe-core") (Flex OS)
20+
- [ot3_firmware]("https://github.com/Opentrons/ot3-firmware") (Flex firmware)
21+
- [buildroot]("https://github.com/Opentrons/buildroot") (OT-2 OS)
2222

23-
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.
23+
```mermaid
24+
flowchart LR
25+
subgraph Shared ["Shared Repositories"]
26+
opentrons["Opentrons/opentrons" ]
27+
opentrons_modules["Opentrons/opentrons-modules" ]
28+
end
2429
25-
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}`:
30+
subgraph Flex ["Flex Only"]
31+
oe_core["Opentrons/oe-core"]
32+
ot3_firmware["Opentrons/ot3-firmware" ]
33+
end
2634
27-
```shell
28-
git checkout release_${version}
29-
git pull
30-
git tag -a v${alphaVersion} -m 'chore(release): ${alphaVersion}'
31-
```
35+
subgraph OT2 ["OT-2 Only"]
36+
buildroot["Opentrons/buildroot" ]
37+
end
3238
33-
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.
39+
OT2Build["OT-2 System Package"]
40+
opentrons --> OT2Build
41+
buildroot --> OT2Build
3442
35-
```shell
36-
git push origin v${alphaVersion}
37-
```
43+
App["Opentrons App"]
44+
opentrons --> App
3845
39-
Changelogs for the release are automatically generated when the tag is pushed and sent to the release page in github.
46+
FlexBuild["Flex System Package"]
47+
opentrons --> FlexBuild
48+
oe_core --> FlexBuild
49+
ot3_firmware --> FlexBuild
50+
opentrons_modules --> OT2Build
51+
opentrons_modules --> FlexBuild
52+
```
4053

41-
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.
54+
These are all versioned and released together. These assets are produced in 2 possible channels:
4255

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

45-
```shell
46-
# note: make sure you have pulled the latest changes for branch
47-
# release_${version} locally before merging into release
48-
git checkout release_${version}
49-
git pull
50-
git checkout release
51-
git pull
59+
> [!TIP]
60+
> using `git config remote.origin.tagOpt --tags` ensures that when you fetch and pull, you get all the tags from the origin remote.
5261
53-
git merge --ff-only release_${version}
54-
git push origin release
55-
```
62+
### Steps to release the changes in `edge`
5663

57-
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:
64+
1. Checkout `edge` and make a chore release branch, without any new changes. The branch name should match `chore_release-${version}`.
5865

5966
```shell
60-
git tag -a v${version} -m 'chore(release): ${version}'
61-
git show v${version}
62-
```
63-
64-
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.
65-
66-
Once the tag looks good, you can push it:
67-
68-
```shell
69-
git push origin v${version}
67+
git switch edge
68+
git pull
69+
git switch -c chore_release-${version}
70+
git push --set-upstream origin chore_release-${version}
7071
```
7172

72-
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.
73-
74-
9. Ensure all deploy jobs succeeded:
75-
76-
- The Opentrons App should be prompting people to update to the new version.
77-
- https://pypi.org/project/opentrons/ should be showing the new version.
78-
79-
10. Release the Python Protocol API docs for this version (see below under Releasing Web Projects).
80-
81-
11. Update the download links on https://opentrons.com/ot-app/. That page is defined in an Opentrons private repository.
82-
83-
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`:
84-
85-
```shell
86-
git checkout edge
87-
git pull
88-
git merge --no-ff release
89-
```
90-
91-
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.
92-
93-
## Releasing Robot Software Stack Hotfixes
94-
95-
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.
73+
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.
9674

97-
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.
75+
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.
9876

99-
```shell
100-
git checkout release
101-
git pull
102-
git checkout -b hotfix_${version}
103-
git push --set-upstream origin hotfix_${version}
104-
```
77+
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}`:
10578

106-
3. Target the hotfix PRs on this branch.
79+
> [!IMPORTANT]
80+
> Use annotated tag (`-a`) with a message (`-m`) for all tags.
10781
108-
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.
82+
```shell
83+
git switch chore_release-${version}
84+
git pull
85+
git tag -a v${alphaVersion} -m 'chore(release): ${alphaVersion}
86+
```
10987
110-
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}`:
88+
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.
11189
11290
```shell
113-
git checkout hotfix_${version}
114-
git pull
115-
git tag -a v${alphaVersion} -m 'chore(release): ${alphaVersion}'
116-
git show v${alphaVersion}
91+
git push origin v${alphaVersion}
11792
```
11893
119-
6. Inspect the created tag and then push it:
94+
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.
12095
121-
```shell
122-
git show v${alphaVersion}
123-
```
96+
7. Once QA is complete, do a final check that the release notes are complete and proof-read.
12497
125-
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.
98+
8. We are ready to `merge -ff-only` the `chore_release-${version}` into `release`.
12699
127-
```shell
128-
git push v${alphaVersion}
129-
```
130-
131-
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.
100+
> [!CAUTION]
101+
> Do **NOT** squash or rebase <br></br>
102+
> Do **NOT** yet push a tag
132103
133-
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):
104+
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:
134105
135-
```shell
136-
# note: make sure you have pulled the latest changes for branch
137-
# release_${version} locally before merging into release
138-
git checkout hotfix_${version}
139-
git pull
140-
git checkout release
141-
git pull
142-
git merge --ff-only release_${version}
143-
git push origin release
144-
```
106+
```shell
107+
git switch chore_release-${version}
108+
git pull
109+
git checkout release
110+
git pull
111+
# now do the merge
112+
git merge --ff-only chore_release-${version}
113+
git push origin release
114+
```
145115
146-
9. Tag the release with its full target version, which we'll call `${version}` since it's no longer an alpha:
116+
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:
147117
148118
```shell
149119
git tag -a v${version} -m 'chore(release): ${version}'
150-
git show v${version}
120+
git log v${version} --oneline -n10
151121
```
152122
153-
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.
123+
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.
154124
155-
Once the tag looks good, push it:
125+
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.
156126
157127
```shell
158128
git push origin v${version}
159129
```
160130
161-
Pushing the tag will create release builds and a github release page with the in-depth changelogs.
131+
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.
162132
163-
10. Ensure all deploy jobs succeeded:
133+
- Flex <https://builds.opentrons.com/ot3-oe/releases.json>
134+
- OT-2 <https://builds.opentrons.com/ot2-br/releases.json>
135+
- App Stable
136+
- <https://builds.opentrons.com/app/latest.yml> Windows
137+
- <https://builds.opentrons.com/app/latest-mac.yml>
138+
- <https://builds.opentrons.com/app/latest-linux.yml>
139+
- App Alpha
140+
- <https://builds.opentrons.com/app/alpha.yml> Windows
141+
- <https://builds.opentrons.com/app/alpha-mac.yml>
142+
- <https://builds.opentrons.com/app/alpha-linux.yml>
143+
- Python `opentrons` package <https://pypi.org/project/opentrons>
144+
- Python `opentrons-shared-data` package <https://pypi.org/project/opentrons-shared-data>
145+
- The Opentrons App should be prompting people to update to the new version given their current channel.
164146
165-
- The Opentrons App should be prompting people to update to the new version.
166-
- https://pypi.org/project/opentrons/ should be showing the new version.
147+
11. Release the Python Protocol API docs for this version (see below under Releasing Web Projects).
167148
168-
11. Update the download links on https://opentrons.com/ot-app/. That page is defined in an Opentrons private repository.
169-
170-
12. Release the Python Protocol API docs for this version (see below under Releasing Web Projects)
171-
172-
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`:
149+
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`:
173150
174151
```shell
175152
git checkout edge
176153
git pull
177154
git merge --no-ff release
178155
```
179156
180-
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.
157+
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.
158+
159+
## Releasing Robot Software Stack Isolated changes
160+
161+
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}`.
181162
182163
### tag usage
183164
184-
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:
165+
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.
166+
167+
#### Tags look like this:
185168
186169
```shell
187170
${projectPrefix}${projectVersion}
188171
```
189172
190173
`${projectPrefix}` is the project name plus `@` for everything but robot stack, where it is `v`.
191174
192-
For instance, the tag for 6.2.1-alpha.3 of the robot stack is `v6.2.1-alpha.3`.
193-
The tag for 4.0.0 of protocol designer is `[email protected]`.
194-
The tag for 0.1.2-beta.1 of ot3 is `[email protected]`.
175+
##### Examples
176+
177+
- the tag for 6.2.1-alpha.3 of the robot stack is `v6.2.1-alpha.3`
178+
- the tag for 0.1.2-beta.1 of an internal release or robot stack is `[email protected]`
179+
- the tag for 4.0.0 of protocol designer is `[email protected]`
195180
196181
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.
197182

0 commit comments

Comments
 (0)