diff options
Diffstat (limited to 'DOCS/release-policy.md')
| -rw-r--r-- | DOCS/release-policy.md | 72 |
1 files changed, 47 insertions, 25 deletions
diff --git a/DOCS/release-policy.md b/DOCS/release-policy.md index 9fb6255cc6..23bc48befd 100644 --- a/DOCS/release-policy.md +++ b/DOCS/release-policy.md @@ -1,13 +1,15 @@ Release Policy ============== -Once or twice a month, a new release is cut off of the master branch and is +Once or twice a year, 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. Releases are tagged on the master branch and will not be maintained separately. +Patch releases may be made if the amount or severity of bugs justify it, or in +the event of security issues. The goal of releases is to provide Linux distributions with something to package. If you want the newest features, just use the master branch. @@ -24,33 +26,43 @@ While on master: - Update the `VERSION` file. -- Update `DOCS/client-api-changes.rst` and `DOCS/interface-changes.rst` - (in particular, update the last version numbers if necessary) +- Update `DOCS/client-api-changes.rst` (in particular, update the last version + number if necessary) + +- Run `TOOLS/gen-interface-changes.py` to refresh `DOCS/interface-changes.rst`, + edit manually as necessary. + +- Delete all `.txt` files in the `DOCS/interface-changes` directory except for `example.txt`. - Create signed commit with changes. - Create signed tag v0.X.Y. -- Add -UNKNOWN suffix to version in `VERSION` file. - -- Commit changes, push release branch (`release/0.X`) and tag to GitHub. +- Push release branch (`release/0.X`) and tag to GitHub. - Create a new GitHub release using the content of `RELEASE_NOTES` related to the new version. +- Readd -UNKNOWN suffix to version in `VERSION` file. + If necessary (to e.g. exclude commits already on master), the release can be done on a branch with different commit history. The release branch **must** then be merged to master so `git describe` will pick up the tag. +This does not apply to patch releases, which are tagged directly on the +`release/0.X` branch. The master branch always remains at v0.X.0. + Release notes template ---------------------- -Here is a template that can be used for writing the `RELEASE_NOTES` file. +Here is a template that can be used for writing the `RELEASE_NOTES` file: ```markdown Release 0.X.Y ============= +This release requires FFmpeg <ver> or newer. + Features -------- @@ -59,20 +71,18 @@ New - List of new features -Removed + +Changed ~~~~~~~ -- List of removed features +- List of changed features -Deprecated -~~~~~~~~~~ -- List of deprecated features +Removed +~~~~~~~ -Behavior --------- +- List of removed features -- List of user-visible changes in behavior Options and Commands -------------------- @@ -82,40 +92,52 @@ Added - List of added options and commands + Changed ~~~~~~~ - List of changed options and commands -Renamed -~~~~~~~ - -- List of renamed options and commands Deprecated ~~~~~~~~~~ - List of deprecated options and commands + Removed ~~~~~~~ - List of removed options and commands + Fixes and Minor Enhancements ---------------------------- - List of fixes and minor enhancements -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. -``` -Note that the "Release 0.X.Y" title should be removed when creating a new GitHub -release. +This listing is not complete. Check DOCS/client-api-changes.rst for a history +of changes to the client API, and DOCS/interface-changes.rst for a history +of changes to other user-visible interfaces. + +A complete changelog can be seen by running `git log <start>..<end>` +in the git repository. +``` 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. + +The changelog of lists all changes since the last release, including those +that have been backported to patch releases already. + +Some additional advice: +- Especially for features, try to reword the messages so that the user-visible + change is clear to the reader. But don't simplify too much or be too verbose. +- It often makes sense to merge multiple related changes into one line +- Changes that have been made and reverted within the same release must not + appear in the changelog +- Limit the "Options and Commands" section to relevant changes +- When filling in the GitHub release, remove the "Release 0.X.Y" heading |