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 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.
2. Having checked out the new release branch, navigate your way over to ./changelogs.
3. Follow the release instructions provided in the README.md located there.
4. Update any version/link references across all specifications.
5. Generate the specification using ./scripts/gendoc.py -c r0.4.0, specifying all the API versions at the time of generation.
6. 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.
7. 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.
8. Tag the release with the format client_server/r0.4.0.
9. Perform a release on GitHub to tag the release.
10. 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.
2. Having checked out the new release branch, navigate your way over to ./changelogs.
3. Follow the "new changelog" instructions provided in the README.md located there.
4. 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.
5. Create/define the appropriate variables in gendoc.py.
6. Update targets.yml.
7. Update any version/link references across all specifications.
8. Follow the regular release process.