matrix-spec-proposals/meta/releasing_a_spec.md

# How to release a specification

There are several specifications that belong to matrix, such as the client-server
specification, server-server specification, and identity service specification. Each
of these gets released independently of each other with their own version numbers.

Once a specification is ready for release, a branch should be created to track the
changes in and to hold potential future hotfixes. This should be the name of the
specification (as it appears in the directory structure of this project) followed
by "release-" and the release version. For example, if the Client-Server Specification
was getting an r0.4.0 release, the branch name would be `client_server/release-r0.4.0`.

*Note*: Historical releases prior to this process may or may not have an appropriate
release branch. Releases after this document came into place will have an appropriate
branch.

The remainder of the process is as follows:
1. Activate your Python 3 virtual environment.
1. Having checked out the new release branch, navigate your way over to `./changelogs`.
1. Follow the release instructions provided in the README.md located there.
1. Update any version/link references across all specifications.
1. Generate the specification using `./scripts/gendoc.py`, specifying all the
   API versions at the time of generation. For example: `./scripts/gendoc.py -c r0.4.0 -s r0.1.0 -i r0.1.0 #etc`
1. PR the changes to the matrix-org/matrix.org repository (for historic tracking).
   * This is done by making a PR to the `unstyled_docs/spec` folder for the version and
     specification you're releasing.
   * Don't forget to symlink the new release as `latest`.
   * For the client-server API, don't forget to generate the swagger JSON by using
     `./scripts/dump-swagger.py -c r0.4.0`. This will also need symlinking to `latest`.
1. Commit the changes and PR them to master. **Wait for review from the spec core team.**
   * Link to your matrix-org/matrix.org so both can be reviewed at the same time.
1. Tag the release with the format `client_server/r0.4.0`.
1. Perform a release on GitHub to tag the release.
1. Yell from the mountaintop to the world about the new release.

### Creating a release for a brand-new specification

Some specifications may not have ever had a release, and therefore need a bit more work
to become ready.

1. Activate your Python 3 virtual environment.
1. Having checked out the new release branch, navigate your way over to `./changelogs`.
1. Follow the "new changelog" instructions provided in the README.md located there.
1. Open the specification RST file and make some changes:
   * Using a released specification as a template, update the changelog section.
   * Use the appropriate changelog variable in the RST.
1. Create/define the appropriate variables in `gendoc.py`.
1. Update `targets.yml`.
1. Update any version/link references across all specifications.
1. Follow the regular release process.