Skip to content

Commit 29d4e92

Browse files
namespacebriannamespacebrian
committed
More adjustments
1 parent 6914075 commit 29d4e92

File tree

1 file changed

+56
-59
lines changed

1 file changed

+56
-59
lines changed

‎docs/steps-to-create-new-terminus-release.md‎

Lines changed: 56 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -24,79 +24,76 @@ If any of these steps should fail, abort the release-cutting process.
2424
- Check the test fixture site: `terminus multidev:list ci-terminus-composer`
2525
- Delete abandoned multidevs older than 1 day: `terminus multidev:delete ci-terminus-composer.<multidev_name> --delete-branch --yes`
2626
- Failed tests leave behind multidevs that accumulate over time and need manual cleanup
27-
2. Get approval from someone authorized to approve Terminus PRs and merge this into your target branch.
27+
2. Await 2 approvals on the PR, but do not merge yet.
28+
3. Proceed to next step, which can be _prepared_ before this PR is approved. This PR and the CCB Jira ticket in the next step have inter-dependencies. The exact sequence is:
29+
1. CCB Jira ticket requires _creation_ of this PR before it can be _drafted_.
30+
2. CCB Jira ticket is not _ready for review_ until tests have passed and this PR is _approved_, but _not merged_.
31+
3. This PR can be merged after CCB approval.
2832

29-
6. ~~Test your work to ensure that Composer won't have trouble installing the application.~~
30-
1. ~~Create a new directory anywhere but in Terminus and change into it before running the test.~~
31-
2. ~~Run this command. Answer `n` (No) if prompted to use another composer.json file in a directory above yours.~~
32-
```
33-
composer require pantheon-systems/terminus:4.x-dev
34-
```
35-
3. ~~If there are no errors, you can delete the directory and proceed.~~
36-
37-
7. Create a CCB Ticket and get approval from the change committee:
33+
6. Draft a Jira ticket in "CCB" project to get approval from the "Change Control Board":
3834
1. **Create CCB Change Request** using Atlassian MCP tools (preferred) or web interface:
3935
- **Project:** CCB
4036
- **Issue Type:** CCB Change Request
4137
- **Squad:** Developer Experience (11058)
4238
- **Service/Component:** terminus
4339
- **Summary:** Terminus X.Y.Z Release
4440
- **Business Justification:** Describe customer benefits
45-
- **Testing:** Reference GitHub Actions + manual testing
41+
- **Testing:** Reference GitHub Actions + manual testing against production
4642
- **Rollback Plan:** Emergency hotfix release to previous version
4743
- **Code Review Link:** GitHub PR URL
4844
- **Risk Assessment:** Typically low risk for additive features
49-
- **Monitoring Plans:** User feedback in Slack/support tickets (exclude GitHub download monitoring)
45+
- **Monitoring Plans:** User feedback in Slack/support tickets.
5046
- **Feature Flag:** None (client-side tool)
5147
- **Urgency:** Normal
5248
- **Tested in Sandbox:** No
53-
2. **Link to related tickets:** Add comment linking to original DEVX ticket
54-
3. **Leave in Draft status** until ready for CCB review
49+
2. **Link to related tickets:** Include a link to the original DEVX ticket.
50+
3. **Leave in Draft status** until ready for CCB review. Ready for CCB review after release PR is _approved_.
5551
4. **Manual creation URL (if needed):** [https://getpantheon.atlassian.net/secure/CreateIssue.jspa?issuetype=ccb-change-request&pid=14450](https://getpantheon.atlassian.net/secure/CreateIssue.jspa?issuetype=ccb-change-request&pid=14450)
56-
57-
8. Once approved, Create a tag:
58-
1. On your local machine, checkout the target branch (e.g. `4.x`) and pull down the latest changes.
59-
2. Create a tag for the new release: `git tag 4.x.x`
60-
3. Push the tag to Github: `git push origin 4.x.x.`
61-
4. Browse to https://github.com/pantheon-systems/terminus/actions where you can see a GitHub Actions workflow has kicked off.
62-
5. This will create a release automatically with the PHAR attached from the start (which prevents a broken `self:update` gap period).
63-
64-
9. Once the release is published, edit the notes to include the changes from this release. It's convenient to copy the markdown from [https://github.com/pantheon-systems/terminus/edit/4.x/CHANGELOG.md](https://github.com/pantheon-systems/terminus/edit/4.x/CHANGELOG.md). Omit the release number and date when copying.
65-
66-
10. For releases `3.x` or later, a PR will be created in the [Homebrew formula](https://github.com/pantheon-systems/homebrew-external) repository. Take a look to it and merge it to release to Homebrew.
67-
68-
11. Update your major branch's version number to `a.b.c+1-dev`, where `a.b.c` is the latest release's version:
69-
1. In `config/constants.yml`, change the value
70-
2. In `CHANGELOG.md`, add a new heading above your most recent release. It should also be in the format of `a.b.c+1-dev`.
71-
72-
12. Open a PR against https://github.com/pantheon-systems/documentation to update the supported versions page [https://github.com/pantheon-systems/documentation/edit/main/source/content/terminus/10-supported-terminus.md](https://github.com/pantheon-systems/documentation/edit/main/source/content/terminus/10-supported-terminus.md).
73-
1. Add the new **Version** at the top of the list. Fill in the **Release Date** with today's date. Leave the **EOL Date** blank.
74-
2. For the most recent release on your major branch, fill in the **EOL Date**. This will be today's date plus one year.
75-
3. If applicable, remove all but one old versions per major branch that are more than one year past EOL from the list. If some of the versions for a major branch have been removed from the list, the last line in the list should read `X.Y.Z or earlier`.
76-
4. If applicable, update the Terminus [PHP Version Compatibility Matrix](https://docs.pantheon.io/terminus/supported-terminus#php-version-compatibility-matrix).
77-
5. Set the PR title to `Terminus Release X.Y.Z - Version Updates` and do the following in the PR template:
78-
1. Use this for your **Summary** section:
79-
`**[Version Updates](https://docs.pantheon.io/terminus/supported-terminus)** - Terminus Release X.Y.Z`
80-
2. In the **Effect** section, add a link to your Terminus Release PR as the only bullet under **The following changes are already committed.**
81-
3. Remove the **Remaining Work and Prerequisites** section.
82-
4. In the **Release** section, fill the **When Ready** box with an `X` and remove the line **After date: $DATE.**
83-
5. Create the PR as ready for approval (not a draft).
84-
85-
13. Create a separate PR for the release notes:
86-
1. Create a new file in `source/releasenotes` for this release. You can use [this example](https://github.com/pantheon-systems/documentation/blob/main/source/releasenotes/2024-12-05-terminus-361.md?plain=1) as a starting point.
87-
2. Set the PR title to `Terminus Release X.Y.Z - Release Notes`
88-
3. Follow the same PR template guidelines as Step 12.
89-
90-
You can also use this as the contents for that PR description (remember to update the version and PR):
91-
92-
```
93-
## Summary
94-
95-
**[Supported Terminus and PHP Versions](https://docs.pantheon.io/terminus/supported-terminus)** - Include Terminus 4.1.0
96-
97-
Also, include new release note.
98-
```
99-
100-
## See Also
52+
5. Proceed to next step, which can be prepared in advance of approvals.
53+
54+
7. Draft a new PR for documentation updates in the `github.com/pantheon-systems/documentation` repo.
55+
1. Acquire up-to-date documentation repo
56+
1. If the documentation repo is already visible in your workspace,
57+
1. Move into it
58+
2. Run `git fetch --all` to pull any recent changes.
59+
3. Run `git branch -vv` to check current branch and if `main` branch is behind at all.
60+
4. Run `git status` to check for clean working directory. If current directory is unclean, `git stash` all changes with a brief message about when and why stash created.
61+
5. Change to `main` branch if not on it already.
62+
6. Ensure main branch fully matches remote by fast-forwarding if branch has not diverged. If branch has diverged, move local version to a new branch `main-dirty-YYYYMMDD` and update `main` to exactly match origin.
63+
2. If the documentation repo is not visible in your workspace, `git clone` it in your available workspace but avoid inadvertently committing as a git submodule.
64+
2. Create a new branch for this release.
65+
3. Update the supported versions page [https://github.com/pantheon-systems/documentation/edit/main/source/content/terminus/10-supported-terminus.md](https://github.com/pantheon-systems/documentation/edit/main/source/content/terminus/10-supported-terminus.md).
66+
1. Add the new **Version** at the top of the list. Fill in the **Release Date** with today's date. Leave the **EOL Date** blank.
67+
2. For the most recent release on your major branch, fill in the **EOL Date**. This will be today's date plus one year. Terminus versions EOL 1 year after they are no longer the latest.
68+
3. If applicable, remove all but one old versions from the list that are more than one year _past EOL_. If any versions are removed, the last line in the list should read `X.Y.Z or earlier`.
69+
4. If applicable, update the Terminus [PHP Version Compatibility Matrix](https://docs.pantheon.io/terminus/supported-terminus#php-version-compatibility-matrix). This will be contextually clear from the changes in this release.
70+
11. Create a new "Release Note" file in `source/releasenotes` for this release. You can use the previous release note as a starting point.
71+
12. Create a new draft PR
72+
1. Set the PR title to `Terminus Release X.Y.Z - Version Updates` and do the following in the PR template:
73+
1. Use this for your **Summary** section:
74+
`**[Version Updates](https://docs.pantheon.io/terminus/supported-terminus)** - Terminus Release X.Y.Z`
75+
2. Add a link to your Terminus Release PR.
76+
3. Include links to the DEVX release ticket and the CCB ticket.
77+
4. Create the PR as a draft.
78+
79+
80+
81+
82+
8. Once both the terminus release PR and the CCB ticket are approved, trigger the release by merging and pushing a new tag. DO NOT create the release via the Github UI!
83+
1. Merge the release PR.
84+
2. On your local machine, checkout the target branch where PR merged to (e.g. `4.x`), and pull the new changes.
85+
3. Create a tag for the new release: `git tag 4.x.x`.
86+
4. Push the tag to Github: `git push origin 4.x.x`. Pushing this tag will trigger release automation.
87+
5. Find and monitor Github Actions workflow using `gh` or browsing to https://github.com/pantheon-systems/terminus/actions. The workflow will take some time (~30+ minutes) to complete.
88+
6. The workflow will create a Github release automatically with the freshly built PHAR attached to it from the start. This prevents a gap period between release creation and PHAR attachment during which `terminus self:update` would be broken for users.
89+
9. Once the release is published, edit the notes to include the changes from this release. It's convenient to simply copy the markdown from [https://github.com/pantheon-systems/terminus/edit/4.x/CHANGELOG.md](https://github.com/pantheon-systems/terminus/edit/4.x/CHANGELOG.md). Omit the release number and date when copying.
90+
10. For releases `3.x` or later, a PR will be created in the [Homebrew formula](https://github.com/pantheon-systems/homebrew-external) repository. Find it and merge it to release to Homebrew.
91+
11. Update the major terminus branch (e.g. `4.x`) "back to dev". The new "dev version" number will be `a.b.c+1-dev`, where `a.b.c` is the version we just released.
92+
1. Create new branch `back_to_<dev version>
93+
2. Update version in `config/constants.yml`.
94+
3. In `CHANGELOG.md`, add a new heading above the latest release.
95+
4. Commit, push, and create a "Back to dev" PR.
96+
97+
## Notes
10198

10299
[Terminus' Usage of Semantic Versioning](https://getpantheon.atlassian.net/wiki/spaces/VULCAN/pages/154438719)

0 commit comments

Comments
 (0)