DOCS: document the new way to handle interface changes

Manually editing interface-changes.rst is a giant maintenance pain that
causes merge conflicts all the time. Stop doing that nonsense and
instead have changes be written to files in DOCS/interface-changes. Also
remove that one sentence in changes.rst because it's just not true.

5 files changed, 30 insertions, 10 deletions

diff --git a/DOCS/contribute.md b/DOCS/contribute.md
index 8323309307..4d2af4ea4e 100644
--- a/DOCS/contribute.md
+++ b/DOCS/contribute.md
@@ -131,12 +131,24 @@ Touching user-visible parts may require updating the mpv docs
 - Changes to command line options (addition/modification/removal) must be
   documented in options.rst.
 - Changes to input properties or input commands must be documented in input.rst.
-- All incompatible changes to the user interface (options, properties, commands)
-  must be documented with a small note in interface-changes.rst. (Additions may
-  be documented there as well, but this isn't required.)
 - Changes to the libmpv API must be reflected in the libmpv's headers doxygen,
   and in client-api-changes.rst.
 
+Interface change policy
+-----------------------
+
+- All incompatible changes to the user interface (options, properties, commands)
+  must be documented by making a new text file with a txt extension containing a
+  small note in the DOCS/interface-changes directory.
+- The name of the file should be brief and related to the commit that makes the
+  change.
+- Grouping multiple related changes in the same file is also OK. Just be sure to
+  put each separate change on a different line.
+- Documenting additions in DOCS/interface-changes is optional but encouraged.
+- interface-changes.rst is never directly updated except when making new major
+  releases.
+- See DOCS/interface-changes/example.txt for an example.
+
 Code formatting
 ---------------
 
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index b80e3635b1..5371fd43fe 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -17,9 +17,12 @@ a large part of the user interface and APIs.
 
 Also see compatibility.rst.
 
-This document lists changes to them. New changes are added to the top. Usually,
-only incompatible or important changes are mentioned. New options/commands/etc.
-are not always listed.
+This document lists changes to them. New options/commands/etc. are not always
+listed.
+
+**Never** write to this file directly except when making releases. New changes
+are added in the interface-changes directory instead. See contribute.md for more
+details.
 
 Interface changes
 =================
diff --git a/DOCS/interface-changes/example.txt b/DOCS/interface-changes/example.txt
new file mode 100644
index 0000000000..c52ee0146f
--- /dev/null
+++ b/DOCS/interface-changes/example.txt
@@ -0,0 +1 @@
+deprecate `--foo`, instead use `--bar=foo` as a replacement
diff --git a/DOCS/man/changes.rst b/DOCS/man/changes.rst
index 63de41c8d2..3f5e0e12c8 100644
--- a/DOCS/man/changes.rst
+++ b/DOCS/man/changes.rst
@@ -10,8 +10,7 @@ There is no real changelog, but you can look at the following things:
 * The git log, which is the "real" changelog
 * The file https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst
   documents changes to the command and user interface, such as options and
-  properties. (It usually documents breaking changes only, additions and
-  enhancements are often not listed.)
+  properties.
 * C API changes are listed in
   https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst
 * The file ``mplayer-changes.rst`` in the ``DOCS`` sub directory on the git
diff --git a/DOCS/release-policy.md b/DOCS/release-policy.md
index 2426ab4e7c..23bc48befd 100644
--- a/DOCS/release-policy.md
+++ b/DOCS/release-policy.md
@@ -26,8 +26,13 @@ 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.