From 336194aee4bc25220f51e2cdf21284d48bfa1bf9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Dec 2021 08:24:43 -0700 Subject: [PATCH] Patch the release process docs (#3568) * Add a release branch to avoid orphaned commits. * Specify a patch process. * Match reality and reference the internal deployment process. This is largely what we do in practice now, including a created `release/v1.1` branch. --- meta/releasing.md | 60 ++++++++++++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 21 deletions(-) diff --git a/meta/releasing.md b/meta/releasing.md index e1480e39..36f01d2d 100644 --- a/meta/releasing.md +++ b/meta/releasing.md @@ -19,10 +19,10 @@ to ensure a consistent and reliable specification. ## The release Assuming the preparation work is complete, all that remains is the actual specification -release. This is done directly on `main`, though local branching for safety is also -welcome. +release. -1. Update the `params.version` section of `config.toml` to use the following template: +1. Create a `release/v1.2` branch where `v1.2` is the version you're about to release. +2. Update the `params.version` section of `config.toml` to use the following template: ```toml [params.version] status = "stable" @@ -36,32 +36,50 @@ welcome. # Today's date. Please use the format implied here for consistency. release_date = "October 01, 2021" ``` -2. Commit the changes. -3. Tag `main` with the spec release with a format of `v1.2` (if releasing Matrix 1.2). -4. Push `main` and the tag. -5. GitHub Actions will run its build steps. Wait until these are successful. If fixes +3. Commit the changes. +4. Tag the branch with the spec release with a format of `v1.2` (if releasing Matrix 1.2). +5. Push the release branch and the tag. +6. GitHub Actions will run its build steps. Wait until these are successful. If fixes need to be made to repair the pipeline or spec build, delete and re-tag the release. -6. Generate the changelog. This is done *after* the tagging to ensure the rendered +7. Check out `main`. +8. Generate the changelog. This is done *after* the tagging to ensure the rendered changelog makes sense. 1. Activate your python virtual environment. 2. Run `./scripts/generate-changelog.sh v1.2 "October 01, 2021"` (using the correct version number and same `release_date` format from the hugo config). 3. Commit the result. -7. Create a new release on GitHub from the newly created tag. +9. Create a new release on GitHub from the newly created tag. * The title should be just "v1.2" (for example). * The description should be a copy/paste of the changelog. The generated changelog will be at `content/partials/changelogs/v1.2.md` - copy/paste verbatim. * Upload the artifacts of the GitHub Actions build for the release to the GitHub - release as artifacts themselves. This should be the tarball that got deployed + release as artifacts themselves. This should be the tarball that will be deployed to spec.matrix.org. -8. Commit a reversion to `params.version` of `config.toml` on `main`: - ```toml - [params.version] - status = "unstable" - current_version_url = "https://spec.matrix.org/latest" - # major = "1" - # minor = "2" - # release_date = "October 01, 2021" - ``` -9. Push pending commits and ensure the unstable spec updates accordingly from the - GitHub Actions pipeline. +10. Commit a reversion to `params.version` of `config.toml` on `main`: + ```toml + [params.version] + status = "unstable" + current_version_url = "https://spec.matrix.org/latest" + # major = "1" + # minor = "2" + # release_date = "October 01, 2021" + ``` +11. Push pending commits and ensure the unstable spec updates accordingly from the + GitHub Actions pipeline. +12. Deploy the release on the webserver. See internal wiki. + +## Patching a release + +From time to time we'll need to update a release in the wild. Examples include fixing typos, +updating build machinery, etc. Typically it is not considered a good idea to patch a release +more than 1 month after the original release date - this is because the administrative effort +is typically best reserved for the next release cycle. + +**Patch releases are not to be used for spec changes. Only typos and equivalent.** + +1. Add the required changes to the release branch (`release/v1.2` for example). +2. Fast forward the `v1.2` tag to the release branch head. +3. Push both the release branch and fast-forwarded tag. +4. Wait for the GitHub Actions build to complete on the tag. +5. Update the assets on the GitHub release to those generated by the latest Actions build. +6. Deploy the release on the webserver. See internal wiki.