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

59
changelogs/README.md
View file

@ -1,60 +1,15 @@
<!-- Note: This is a markdown file so the build script's RST processing doesn't grab it -->
# Changelogs
[Towncrier](https://github.com/hawkowl/towncrier) is used to manage the changelog and
keep it up to date. Because of this, updating a changelog is really easy.
## How to update a changelog when releasing an API
## Generating the changelog
1. Ensure you're in your Python 3 virtual environment
2. `cd` your way to the API you're releasing (eg: `cd changelogs/client_server`)
3. Run `towncrier --version "r0.4.0" --name "client-server" --yes` substituting the
variables as approprite. Note that `--name` is required although the value is ignored.
4. Commit the changes and finish the release process.
Please see the [release docs](../meta/releasing.md) for more information.
## How to prepare a changelog for a new API
## Creating a new changelog
For this example, we're going to pretend that the `server_server` API doesn't exist.
1. Create the file `changelogs/server_server.rst`
2. Create the folder `changelogs/server_server`
3. In the new folder, create a `pyproject.toml` file with these contents:
```toml
[tool.towncrier]
filename = "../server_server.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "removal"
name = "Removed Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true
```
4. Create a `.gitignore` in `changelogs/server_server/newsfragments` with the contents `!.gitignore`
There are a few places you'll have to update:
* `/layouts/shortcodes/changelog/changelog-changes.html` to account for the new changelog.
* `/scripts/generate-changelog.sh` to render the changelog for releases.
* Supporting documentation such as the contributing guidelines.