diff options
Diffstat (limited to 'DOCS/release-policy.md')
| -rw-r--r-- | DOCS/release-policy.md | 182 |
1 files 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: <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. -```markdown -Release 0.X.Y -============= +``Fixes: <commit-ID>`` -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: <commit-ID>`` -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: <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. -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: <text>`` -Options and Commands --------------------- + Add a changelog entry with the given text. -Added -~~~~~ +``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``. -Changed -~~~~~~~ + 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. -Renamed -~~~~~~~ +- 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. -Deprecated -~~~~~~~~~~ +- 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. -Removed -~~~~~~~ +- 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 -release. +- 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. |