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

Patch the release process docs (#3568)

Browse source 
* Add a release branch to avoid orphaned commits.
* Specify a patch process.
* Match reality and reference the internal deployment process.

This is largely what we do in practice now, including a created `release/v1.1` branch.
This commit is contained in:
Travis Ralston 2021-12-21 08:24:43 -07:00 • committed by GitHub
parent 71988263f3
commit 336194aee4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 39 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

42
meta/releasing.md
View file

@ -19,10 +19,10 @@ to ensure a consistent and reliable specification.
## The release ## The release
Assuming the preparation work is complete, all that remains is the actual specification 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 release.
welcome.
1. Update the `params.version` section of `config.toml` to use the following template: 1. Create a `release/v1.2` branch where `v1.2` is the version you're about to release.
2. Update the `params.version` section of `config.toml` to use the following template:
```toml ```toml
[params.version] [params.version]
status = "stable" status = "stable"
@ -36,25 +36,26 @@ welcome.
# Today's date. Please use the format implied here for consistency. # Today's date. Please use the format implied here for consistency.
release_date = "October 01, 2021" release_date = "October 01, 2021"
``` ```
2. Commit the changes. 3. Commit the changes.
3. Tag `main` with the spec release with a format of `v1.2` (if releasing Matrix 1.2). 4. Tag the branch with the spec release with a format of `v1.2` (if releasing Matrix 1.2).
4. Push `main` and the tag. 5. Push the release branch and the tag.
5. GitHub Actions will run its build steps. Wait until these are successful. If fixes 6. 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. 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 7. Check out `main`.
8. Generate the changelog. This is done *after* the tagging to ensure the rendered
changelog makes sense. changelog makes sense.
1. Activate your python virtual environment. 1. Activate your python virtual environment.
2. Run `./scripts/generate-changelog.sh v1.2 "October 01, 2021"` (using the correct 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). version number and same `release_date` format from the hugo config).
3. Commit the result. 3. Commit the result.
7. Create a new release on GitHub from the newly created tag. 9. Create a new release on GitHub from the newly created tag.
* The title should be just "v1.2" (for example). * The title should be just "v1.2" (for example).
* The description should be a copy/paste of the changelog. The generated changelog * 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. 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 * 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 release as artifacts themselves. This should be the tarball that will be deployed
to spec.matrix.org. to spec.matrix.org.
8. Commit a reversion to `params.version` of `config.toml` on `main`: 10. Commit a reversion to `params.version` of `config.toml` on `main`:
```toml ```toml
[params.version] [params.version]
status = "unstable" status = "unstable"
@ -63,5 +64,22 @@ welcome.
# minor = "2" # minor = "2"
# release_date = "October 01, 2021" # release_date = "October 01, 2021"
``` ```
9. Push pending commits and ensure the unstable spec updates accordingly from the 11. Push pending commits and ensure the unstable spec updates accordingly from the
GitHub Actions pipeline. GitHub Actions pipeline.
12. Deploy the release on the webserver. See internal wiki.
## Patching a release
From time to time we'll need to update a release in the wild. Examples include fixing typos,
updating build machinery, etc. Typically it is not considered a good idea to patch a release
more than 1 month after the original release date - this is because the administrative effort
is typically best reserved for the next release cycle.
**Patch releases are not to be used for spec changes. Only typos and equivalent.**
1. Add the required changes to the release branch (`release/v1.2` for example).
2. Fast forward the `v1.2` tag to the release branch head.
3. Push both the release branch and fast-forwarded tag.
4. Wait for the GitHub Actions build to complete on the tag.
5. Update the assets on the GitHub release to those generated by the latest Actions build.
6. Deploy the release on the webserver. See internal wiki.