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

Update release documentation (Q2 2024 edition) (#1759)

Browse source 
* Update release documentation (Q2 2024 edition)

* changelog

* Drop the ranges we don't follow

* Don't discourage maintenance

* Patch releases just aren't a good idea
This commit is contained in:
Travis Ralston 2024-06-19 22:08:20 -06:00 • committed by GitHub
parent 9c46fa3f35
commit 560f29cff3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 43 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

24
.github/ISSUE_TEMPLATE/release.md vendored
View file

@ -16,20 +16,22 @@ Previous release: <!-- LINK TO LAST RELEASE'S CHECKLIST -->
Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
* [ ] Pin this issue to the repo.
* [ ] Ensure the social media account holders are available for the release day. * [ ] Ensure the social media account holders are available for the release day.
* [ ] Blog post written * [ ] Blog post written.
* [ ] Check for release blockers that may have been missed * [ ] Check for release blockers that may have been missed.
* [ ] Review/fix the changelog * [ ] Review/fix the changelog.
Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
* [ ] Branch stuffs * [ ] Branch stuffs.
* [ ] Github release artifact * [ ] Github release artifact.
* [ ] Published to spec.matrix.org * [ ] Published to spec.matrix.org.
* [ ] All links work * [ ] All links work.
* [ ] Publish blog post * [ ] Publish blog post.
* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted * [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted.
* [ ] Post to Twitter/Mastodon * [ ] Post to Twitter/Mastodon.
* [ ] Close this issue * [ ] Close this issue.
* [ ] Unpin this issue from the repo.
Known release blockers: Known release blockers:
* [ ] <!-- Issue/PR link --> * [ ] <!-- Issue/PR link -->

1
changelogs/internal/newsfragments/1759.clarification Normal file
View file

@ -0,0 +1 @@
Update the spec release process and related documentation.

59
meta/releasing.md
View file

@ -6,48 +6,43 @@ machinery works.
## Timeline ## Timeline
The spec is released each calendar quarter. The target release dates are within the The spec is released each calendar quarter. The *target* months are:
following ranges:
* Q1: January 20-27 (critically, before FOSDEM). * Q1: January or February.
* Q2: May 20-27. * Q2: May.
* Q3: August 20-27. * Q3: August.
* Q4: November 1-15 (before recurring November conflicts, like IETF). * Q4: November.
The SCT aims to have dates picked out by: The SCT aims to have dates picked out 2 weeks before the chosen release date. When
possible, releases should be scheduled for Thursdays and Fridays to allow a few
* Q1: January 10. consecutive business days for identifying blockers.
* Q2: May 1.
* Q3: August 1.
* Q4: October 15.
When a release date is picked, a [checklist](https://github.com/matrix-org/matrix-spec/issues/new?assignees=&labels=release-blocker&projects=&template=release.md&title=Matrix+1.X) When a release date is picked, a [checklist](https://github.com/matrix-org/matrix-spec/issues/new?assignees=&labels=release-blocker&projects=&template=release.md&title=Matrix+1.X)
issue is created to track details of the release. Release blockers should continue to issue is created to track details of the release. Release blockers should continue
be accepted up until 7 calendar days prior to the release date. to be accepted at the discretion of whoever is doing the release (typically, blockers
should be allowed up to 1-2 days before the release date).
**Release dates are not promises.** The SCT reserves the ability to change, cancel, **Release dates are not promises.** The SCT reserves the ability to change, cancel,
postpone, etc a release for any reason. Do not rely on a release happening on a given postpone, etc a release for any reason. Do not rely on a release happening on a given
day until the release has actually happened & blog post published. day until the release has actually happened & blog post published.
Once a release is scheduled, the SCT will begin planning what the next release is Once a release is *scheduled*, the SCT will begin planning what the next release is
expected to look like. The plan should be included in the spec release blog post, expected to look like. The plan should be included in the spec release blog post,
and be ready for execution on spec release day. Plans are guides and not promises. and be ready for execution on spec release day. Plans are guides and not promises.
A blog post for the SCT members to review should be ready at minimum 1 week before A blog post for the SCT members to review should be ready 2-3 days prior to the
the target release date. 1-2 days before the release itself, the prerequisite steps release at minimum. Preferably a week in advance.
below are executed to ensure the spec release can go ahead.
1-2 days before the release itself, the prerequisite steps below are executed to
ensure the spec release can go ahead.
## Release composition ## Release composition
*This section is a work in progress.* *This section is a work in progress.*
Mentioned above, the SCT aims to have spec releases quarterly. Each quarter has a Spec releases do not currently have attached themes, though when planning a release
slightly different theme to it: a broad theme may be considered. Ideally, each release contains a "hero feature"
which is highlighted in the later blog post.
* Q1: Massive feature release, if possible. This generally happens thanks to FOSDEM.
* Q2: Regular feature release, if possible.
* Q3: Momentum-continuing feature release, if possible.
* Q4: Preferably a maintenance release, but will accept features per normal.
## Prerequisites / preparation ## Prerequisites / preparation
@ -115,12 +110,16 @@ release.
## Patching a release ## Patching a release
From time to time we'll need to update a release in the wild. Examples include fixing typos, Patch releases are used to fix the most recent release on record. Typically a patch
updating build machinery, etc. Typically it is not considered a good idea to patch a release release will be deployed if there is an issue with the build machinery, a factual
more than 1 month after the original release date - this is because the administrative effort error is introduced by the release, or there are notable clarity issues introduced
is typically best reserved for the next release cycle. by the release which may affect implementation. It's usually not a good idea to
ship a patch release if it can be avoided.
**Patch releases are not to be used for spec changes. Only typos and equivalent.** Typos and similar do not generally require a patch release.
**Patch releases must not to be used for spec changes (new MSCs, etc) beyond fixing
factual errors.**
1. Add the required changes to the release branch (`release/v1.2` for example). 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. 2. Fast forward the `v1.2` tag to the release branch head.