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 the changelog section of the specification you're releasing to make a reference to the new version.
5. Update any version/link references across all specifications.
6. Ensure the targets.yml file lists the version correctly.
7. Commit the changes and PR them to master.
8. Tag the release with the format client_server/r0.4.0.
9. 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.
   • Don't forget to symlink the new release as latest.
10. Perform a release on GitHub to tag the release.
11. 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.