From d8b9c00e4a4045cebdd15d793c85fc171204e52d Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 13 Sep 2019 18:02:55 +0200 Subject: Proposal --- DOCS/release-policy.md | 182 ++++++++++++++++++++++++++++++------------------- 1 file changed, 110 insertions(+), 72 deletions(-) diff --git a/DOCS/release-policy.md b/DOCS/release-policy.md index 507f4c440e..f6cbe3a5dc 100644 --- a/DOCS/release-policy.md +++ b/DOCS/release-policy.md @@ -1,117 +1,155 @@ Release Policy ============== -Once or twice a month, a new release is cut off of the master branch and is -assigned a 0.X.Y version number, where X is incremented each time a release -contains breaking changes, such as changed options or added/removed features, -and Y is incremented if a release contains only bugfixes and other minor -changes. +Note: this is a proposal and pending for implementation. + +Occasionally, a new release is made from the master branch and is assigned a +1.X.Y version number. Normally, Y is incremented if the release contains bug +fixes or minor changes only. If X is incremented, Y is reset to 0. Releases are tagged on the master branch and will not be maintained separately. +Releases other than the latest release are unsupported and unmaintained. -The goal of releases is to provide Linux distributions with something to -package. If you want the newest features, just use the master branch. -We try our best to keep it deployable at all times. +Releases are made automatically. Commit messages contain control tags, that +affect the release note contents, the release date, and whether a minor or +major release will be made. The timing of releases completely depends on the +actual development pace. -Releases other than the latest release are unsupported and unmaintained. +Minor releases +-------------- -Release procedure ------------------ +Minor releases contain the following types of changes: -While on master: +- Critical or minor bug fixes to a previous release (minor or major) -- Update the `RELEASE_NOTES` file. +- Small maintenance changes of no larger consequences -- Update the `VERSION` file. +- Minor features -- Update `DOCS/client-api-changes.rst` and `DOCS/interface-changes.rst` - (in particular, update the last version numbers if necessary) +Major releases +-------------- -- Commit changes. +Major releases contain changes that affect the user or features that are +considered interesting. Breaking changes also must happen on major releases. + +Breaking changes +---------------- + +By definition, a breaking change is a change that is incompatible to the +previous release. Normally, a breaking change must be announced 6 months +in advance using a deprecation (listed in the changelog, and optionally logged +by mpv at runtime). The actual change must happen only on a major release. + +It is possible that a deadlock with breaking changes and fixes happens. On one +hand, a breaking change is supposed to be releases only after the 6 month +deprecation, on the other hand, unrelated bug fixes should be released +immediately. This is solved using two mechanisms: requiring developers to honor +the deprecation period manually, and making releases that break the policy. + +Tags for controlling releases +----------------------------- + +Most commits will require control tags for releases. They are part of the +commit message, separated by new lines. List of tags: -- Create signed tag v0.X.Y. +``Type: `` -- Add -UNKNOWN suffix to version in `VERSION` file. + The type of the commit, if release relevant. -- Commit changes, push branch and tag to GitHub. + If the "Severity" or "Fixes" tags are used, the Type must be "bug fix", or + if the tag is not present, is implied to be this value. -- Create a new GitHub release using the content of `RELEASE_NOTES` related to - the new version. +``Fixes: #`` -Release notes template ----------------------- + Indicate that a bug was fixed, using the issue number in the issue tracker + associated with the hoster of the git repository's main mirror. -Here is a template that can be used for writing the `RELEASE_NOTES` file. + The issue link may be included in the generated release notes. -```markdown -Release 0.X.Y -============= +``Fixes: `` -Features --------- + This commit fixes a previous commit. The previous commit was buggy and + didn't work properly. The releaser must take this into account. -New -~~~ + There can be multiple lines like this, each giving a new commit ID. -- List of new features +``Depends: `` -Removed -~~~~~~~ + This commit requires a previous commit. This may be used in case the release + workflow includes cherry-picking, but will be pointless otherwise. -- List of removed features + "removal" commits may reference a commit that deprecated the removed thing. -Deprecated -~~~~~~~~~~ +``Severity: `` -- List of deprecated features + This commit is a bug fix, and the tag controls the severity of the fix. + "minor" is the implicit default. "major" will trigger a release within a + week. "critical" will trigger a release within 2 days. "security" will in + addition mark the release as security fix. -Behavior --------- + If a bug fix is critical, but the impact is minor (e.g. rarely used feature, + which was completely broken), the Severity may be adjusted down accordingly. -- List of user-visible changes in behavior +``Release-note: `` -Options and Commands --------------------- + Add a changelog entry with the given text. -Added -~~~~~ +``Interface-change: