matrix-spec/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 server 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 the changelog section of the specification you're releasing to make a reference
   to the new version.
1. Update any version/link references across all specifications.
1. Update the index to list the version correctly.
1. Add 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.
1. Commit the changes and PR them to master.
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.