diff options
1 files changed, 110 insertions, 72 deletions
diff --git a/DOCS/ b/DOCS/
index 507f4c440e..f6cbe3a5dc 100644
--- a/DOCS/
+++ b/DOCS/
@@ -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
+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: <feature|bug fix|removal|deprecation|change>``
-- 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: #<bug-ID>``
-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.
-Release 0.X.Y
+``Fixes: <commit-ID>``
+ This commit fixes a previous commit. The previous commit was buggy and
+ didn't work properly. The releaser must take this into account.
+ There can be multiple lines like this, each giving a new commit ID.
-- List of new features
+``Depends: <commit-ID>``
+ 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.
+``Severity: <minor|major|critical|security>``
-- 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.
+ 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: <text>``
-Options and Commands
+ Add a changelog entry with the given text.
+``Interface-change: <option/property/command-name>``
-- List of added options and commands
+ This commit changes the option, property, or command with the given name.
+ Example: ``Interface-change: --fullscreen option``.
+ Typically, this commit will also modify interface-changes.rst.
-- List of changed options and commands
+``Release-control: major``
+ The next release should be a major release, even if the release logic
+ indicates a minor release according to the commit history.
+Release script
+The release script checks the commits since the last commits on every git push.
+It will analyze the tags, and determine when the next release should happen,
+and whether it's a minor or major release. The tags will also be used to
+generate the release notes.
+(A human can be used until such a script is written.)
+The script will modify perform the following steps:
+- Update `DOCS/client-api-changes.rst` and `DOCS/interface-changes.rst`
+ (in particular, update the last version numbers if necessary)
+- Commit changes.
+- Create tag v1.X.Y.
-- List of renamed options and commands
+- Create `RELEASE_NOTES` and `VERSION` files, fill them with generated contents.
+ Do not commit these changes.
+- Create a tar.gz of the checkout.
-- List of deprecated options and commands
+- Create a new GitHub release using the tar.gz, and the use `RELEASE_NOTES`
+ file as release text.
+- Push the changes to github master, discard the uncomitted changes.
-- List of removed options and commands
+It will adhere to the following timings:
-Fixes and Minor Enhancements
+- If there are new commits in github master, which are not tagged as release
+ worthy, but which have non-empty metadata (basically, which lead to non-empty
+ release notes), make a minor release after 3 weeks of inactivity.
-- List of fixes and minor enhancements
+- If there is a "minor" severity change, or a new feature, or a deprecation,
+ make a minor release after 1 week of no other such changes being added to
+ git master.
-This listing is not complete. There are many more bug fixes and changes. The
-complete change log can be viewed by running `git log <start>..<end>` in
-the git repository.
+- If there is a "major" severity change, make a major release after 2 weeks of
+ no other activity, or after 4 weeks at the latest.
-Note that the "Release 0.X.Y" title should be removed when creating a new GitHub
+- If there is a "security" severity change, make a new release after 6 hours.
+ The release is major or minor depending on previous unreleased commits.
-When creating a new point release its changes should be added on top of the
-`RELEASE_NOTES` file (with the appropriate title) so that all the changes in
-the current 0.X branch will be included. This way the `RELEASE_NOTES` file
-can be used by distributors as changelog for point releases too.
+All this assumes a branch-less release model, that does not involve cherry-
+picking individual fixes into release branches.