Merge branch 'matrix-org:main' into main

Author: gleachkr

changelogs/client_server/newsfragments/3562.clarification

@@ -0,0 +1 @@
+Clarify that `base_url` in client `well_known` may or may not include trailing slash.

config-circleci.toml

@@ -285,10 +285,10 @@ specify parameter values. The flow for this method is as follows:
         1.  If the content cannot be parsed, then `FAIL_PROMPT`.
     4.  Extract the `base_url` value from the `m.homeserver` property.
         This value is to be used as the base URL of the homeserver.
-        1.  If this value is not provided, then `FAIL_PROMPT`.
+        1. If this value is not provided, then `FAIL_PROMPT`.
     5.  Validate the homeserver base URL:
-        1.  Parse it as a URL. If it is not a URL, then `FAIL_ERROR`.
-        2.  Clients SHOULD validate that the URL points to a valid
+        1. Parse it as a URL. If it is not a URL, then `FAIL_ERROR`.
+        2. Clients SHOULD validate that the URL points to a valid
             homeserver before accepting it by connecting to the
             [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) endpoint, ensuring that it does
             not return an error, and parsing and validating that the
@@ -297,6 +297,8 @@ specify parameter values. The flow for this method is as follows:
             done as a simple check against configuration errors, in
             order to ensure that the discovered address points to a
             valid homeserver.
+        3. It is important to note that the `base_url` value might include
+           a trailing `/`. Consumers should be prepared to handle both cases.
     6.  If the `m.identity_server` property is present, extract the
         `base_url` value for use as the base URL of the identity server.
         Validation for this URL is done as in the step above, but using

content/client-server-api/_index.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.