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

@@ -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
+release.
-welcome.
 
-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. Commit the changes.
-3. Tag `main` with the spec release with a format of `v1.2` (if releasing Matrix 1.2).
+4. Tag the branch with the spec release with a format of `v1.2` (if releasing Matrix 1.2).
-4. Push `main` and the tag.
+5. Push the release branch and the tag.
-5. GitHub Actions will run its build steps. Wait until these are successful. If fixes
+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`:
+10. Commit a reversion to `params.version` of `config.toml` on `main`:
-   ```toml
+    ```toml
-   [params.version]
+    [params.version]
-   status = "unstable"
+    status = "unstable"
-   current_version_url = "https://spec.matrix.org/latest"
+    current_version_url = "https://spec.matrix.org/latest"
-   # major = "1"
+    # major = "1"
-   # minor = "2"
+    # minor = "2"
-   # release_date = "October 01, 2021"
+    # release_date = "October 01, 2021"
-   ```
+    ```
-9. Push pending commits and ensure the unstable spec updates accordingly from the
+11. Push pending commits and ensure the unstable spec updates accordingly from the
-   GitHub Actions pipeline.
+    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.