wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Release process: changelog generation and docs (#3446)

Browse source 
* Remove extra pyprojects and update changelog docs

* Add script for rendering the changelog

* Add docs for how to release the spec

* Move legacy changelogs out of the way
This commit is contained in:
Travis Ralston 2021-10-18 10:09:35 -06:00 • committed by GitHub
parent 61ac438871
commit e8674688e6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
22 changed files with 172 additions and 282 deletions
Download patch file Download diff file Expand all files Collapse all files

67
meta/releasing.md Normal file
View file

@ -0,0 +1,67 @@
# How to release the specification
The whole specification is now released as a single unit/artifact. This document is
the process for releasing the specification and a description of how the (public)
machinery works.
## Prerequisites / preparation
First, can we even release the spec? This stage is mostly preperation work needed
to ensure a consistent and reliable specification.
1. Ensure `main` is committed with all the spec changes you expect to be there.
2. Review the changelog to look for typos, wording inconsistencies, or lines which
can be merged. For example, "Fix typos" and "Fix spelling" can be condensed to
"Fix various typos throughout the specification".
3. Do a quick skim to ensure changelogs reference the MSCs which brought the changes
in. They should be linked to the GitHub MSC PR (not the markdown document).
## 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.
1. Update the `params.version` section of `config.toml` to use the following template:
```toml
[params.version]
status = "stable"
current_version_url = "https://spec.matrix.org/latest"
# This will be the spec version you're releasing. If that's v1.2, then `major = "1"`
# and `minor = "2"`
major = "1"
minor = "2"
# 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
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
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.
* 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
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.