Skip to content

Commit b0b940a

Browse files
sandhosesandhose
committed
Release documentation
1 parent 8df03bf commit b0b940a

File tree

2 files changed

+124
-0
lines changed

2 files changed

+124
-0
lines changed

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
# Development
4141

4242
- [Contributing](./development/contributing.md)
43+
- [Releasing](./development/releasing.md)
4344
- [Architecture](./development/architecture.md)
4445
- [Database](./development/database.md)
4546
- [Internal GraphQL API](./development/graphql.md)

‎docs/development/releasing.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Releasing
2+
3+
MAS follows the same release cadence as Synapse, meaning usually one full release cycle every two weeks, with one week of release candidates.
4+
5+
## GitHub Action workflows
6+
7+
There are four main GitHub Action workflows involved in releasing MAS:
8+
9+
### [`translations-download` workflow]
10+
11+
This workflow downloads the latest translations from [Localazy] onto the target branch.
12+
It is intended to be run before the start of each release cycle on the main branch and before each release on the release branch.
13+
14+
Before running it, make sure to review pending translations in [Localazy], enabling new languages that pass the 70% threshold.
15+
16+
### [`release-branch` workflow]
17+
18+
This workflow starts a new major/minor release branch and bumps the version to the next major/minor pre-version.
19+
It will tag the version, triggering the `build` workflow for it.
20+
21+
The next major/minor pre-version is computed from the current version on the main branch, so it works as follows:
22+
23+
- `v1.2.3` will become `v2.0.0-rc.0` for a major release
24+
- `v1.2.3` will become `v1.3.0-rc.0` for a minor release
25+
26+
The release branch will be called `release/vX.Y`, and a PR will be automatically opened to merge it into the main branch.
27+
28+
29+
### [`release-bump` workflow]
30+
31+
This workflow bumps the version on a release branch to either the next stable version or the next release candidate version.
32+
This *cannot* be run on the main branch (and will fail if you try).
33+
34+
This workflow has three meaningful inputs:
35+
36+
- The release branch to bump
37+
- Whether the release is a pre-release or not:
38+
- If it is a pre-release, `v1.2.3-rc.0` will become `v1.2.3-rc.1`, and `v1.2.3` will become `v1.2.4-rc.0`.
39+
- If it is not a pre-release, `v1.2.3-rc.0` will become `v1.2.3`, and `v1.2.3` will become `v1.2.4`.
40+
- Whether the release branch should be merged back into the main branch or not. In most cases, this should be enabled unless doing a release on a previous release branch.
41+
42+
### [`build` workflow]
43+
44+
This workflow is automatically run in three conditions:
45+
46+
- When a `v*` tag is pushed
47+
- On the `main` branch
48+
- When a PR is tagged with the `Z-Build-Workflow` label (**note that this doesn't work on PRs from forks**)
49+
50+
In all cases, it will build and push a container image to ghcr.io and build binaries to GitHub Action assets.
51+
52+
For `v*` tags:
53+
54+
- It will push the container image with the `MAJOR`, `MAJOR.MINOR`, `MAJOR.MINOR.PATCH`, `sha-HASH`, and `latest` tags for stable releases.
55+
- It will push the container image with the `MAJOR.MINOR.PATCH-rc.N` and `sha-HASH` tags for pre-releases.
56+
- It will **draft** a release on GitHub, with generated changelogs, reference to the built container image, and pre-built binaries attached to the release.
57+
58+
On the main branch:
59+
60+
- It will push the container image with the `sha-HASH` and `main` tags.
61+
- It will update the [`unstable`](https://github.com/element-hq/matrix-authentication-service/releases/tag/unstable) GitHub release with the built container image and pre-built binaries.
62+
63+
When a PR is tagged with the `Z-Build-Workflow` label:
64+
65+
- It will push the container image with the `sha-HASH` and `pr-NUMBER` tags.
66+
- It will comment on the PR with the built container image.
67+
- Pre-built binaries are available in the workflow artifacts.
68+
69+
70+
## Changelog generation
71+
72+
Changelogs are automatically generated from PR titles and labels with the GitHub tools.
73+
74+
The configuration for those can be found in the `.github/release.yml`, but the main labels to be aware of are:
75+
76+
- `T-Defect`: Bug fixes
77+
- `T-Enhancement`: New features
78+
- `A-Admin-API`: Changes to the admin API
79+
- `A-Documentation`: Documentation
80+
- `A-I18n`: Translations
81+
- `T-Task`: Internal changes
82+
- `A-Dependencies`: Dependency updates
83+
84+
They are calculated based on the previous release. For release candidates, this includes the previous release candidate.
85+
86+
## Undrafting releases
87+
88+
Releases are manually undrafted when the release is ready to be published.
89+
At this point, the releaser should check the changelog and ensure the "Set as pre-release" and "Set as latest release" checkboxes are checked as appropriate.
90+
91+
## Full release process
92+
93+
- Start a new release cycle:
94+
1. Run the [`translations-download` workflow] on the main branch.
95+
1. Wait for the [translation download PR] to be automatically merged.
96+
1. Run the [`release-branch` workflow] on the main branch.
97+
1. Wait for [CI to churn] and the [draft release to appear]. This takes about 30 minutes.
98+
1. Double-check the changelog on the draft release.
99+
1. Check the "Set as pre-release" checkbox, and publish the release.
100+
1. Delete the N-2 release branch on [Localazy], meaning that once the 0.16 release cycle begins, the 0.14 release branch will be deleted.
101+
- Create new release candidates if needed:
102+
1. Run the `translations-download` workflow on the release branch.
103+
1. Wait for the [translation download PR] to be automatically merged.
104+
1. Run the [`release-bump` workflow] on the release branch, with the `rc` input **checked**.
105+
1. Wait for [CI to churn] and the [draft release to appear]. This takes about 30 minutes.
106+
1. Double-check the changelog on the draft release.
107+
1. Check the "Set as pre-release" checkbox and publish the release.
108+
- Create a new stable release:
109+
1. Run the [`translations-download` workflow] on the release branch
110+
1. Wait for the [translation download PR] to be automatically merged
111+
1. Run the [`release-bump` workflow] on the release branch, with the `rc` input **unchecked**.
112+
1. Wait for [CI to churn] and the [draft release to appear]. This takes about 30 minutes.
113+
1. Double-check the changelog on the draft release.
114+
1. Check the "Set as latest release" checkbox and publish the release.
115+
116+
[Localazy]: https://localazy.com/p/matrix-authentication-service
117+
[`translations-download` workflow]: https://github.com/element-hq/matrix-authentication-service/actions/workflows/translations-download.yaml
118+
[`release-branch` workflow]: https://github.com/element-hq/matrix-authentication-service/actions/workflows/release-branch.yaml
119+
[`release-bump` workflow]: https://github.com/element-hq/matrix-authentication-service/actions/workflows/release-bump.yaml
120+
[`build` workflow]: https://github.com/element-hq/matrix-authentication-service/actions/workflows/build
121+
[translation download PR]: https://github.com/element-hq/matrix-authentication-service/pulls?q=is%3Apr+label%3AA-I18n
122+
[CI to churn]: https://github.com/element-hq/matrix-authentication-service/actions/workflows/build.yaml?query=event%3Apush+actor%3Amatrixbot
123+
[draft release to appear]: https://github.com/element-hq/matrix-authentication-service/releases

0 commit comments

Comments
 (0)