From 58363d209c2bb24c6265adfb6efa81c716bf8db7 Mon Sep 17 00:00:00 2001 From: Dudemanguy Date: Wed, 28 Feb 2024 10:24:09 -0600 Subject: [PATCH] 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. --- DOCS/contribute.md | 18 +++++++++++++++--- DOCS/interface-changes.rst | 9 ++++++--- DOCS/interface-changes/example.txt | 1 + DOCS/man/changes.rst | 3 +-- DOCS/release-policy.md | 9 +++++++-- 5 files changed, 30 insertions(+), 10 deletions(-) create mode 100644 DOCS/interface-changes/example.txt 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.