diff options
Diffstat (limited to 'DOCS/compatibility.rst')
| -rw-r--r-- | DOCS/compatibility.rst | 22 |
1 files changed, 20 insertions, 2 deletions
diff --git a/DOCS/compatibility.rst b/DOCS/compatibility.rst index 3d6ec2cdfc..aeef8fc7ca 100644 --- a/DOCS/compatibility.rst +++ b/DOCS/compatibility.rst @@ -29,7 +29,16 @@ All of these are important for interfacing both with end users and API users (which include Lua scripts, libmpv, and the JSON IPC). As such, they constitute a large part of the user interface and APIs. -All incompatible changes to this must be declared in interface-changes.rst. +Certain options and commands may have documented default values. These default +values are considered a part of the API since scripts may already rely on these +documented behaviors. Changing these defaults are considered incompatible +changes and must be documented. Undocumented default values do not subject to +this requirement, and it is recommended to discourage such usage in the related +documentations if there is a need to frequently change such defaults. + +All incompatible changes to this must be declared in interface-changes.rst, +which include the types of changes, the impact of these changes, and suggested +actions to address such impact so that the incompatibility is alleviated. (This may also list compatible additions, but it's not a requirement.) Degrees of importance and compatibility preservation @@ -49,8 +58,17 @@ functionality still works, and a replacement is available (if technically reasonable). For example, a feature deprecated in mpv 0.30.0 may be removed in mpv 0.32.0. Minor releases do not count towards this. +Under extraordinary circumstances, such as missed incompatible changes that are +already included in a release, critical security fixes, or a severe shortage of +developer time to address the known incompatible changes, important/often used +parts may be broken immediately, but the change must be extensively documented: +all of the related documentations (including manpage, interface-changes.rst, +etc., retrospectively modified if applicable) must clearly state the following: +the fact that the change is a breaking change; the version when the breaking +change happened; and the reason, impact, and suggested remedy actions. + Less useful parts can be broken immediately, but must come with some sort of -removal warning- +removal warning. Parts for debugging and testing may be removed any time, potentially even without any sort of documentation. |