From 46dbaff961bc9d869b844a2dcc0a7dbf4e6915d2 Mon Sep 17 00:00:00 2001
From: nanahi <130121847+na-na-hi@users.noreply.github.com>
Date: Thu, 16 May 2024 02:17:57 -0400
Subject: [PATCH] DOCS/compatibility.rst: add requirement when changing default
 values

Documented default values are relied upon by scripts, so changing these
values can casuse incompatible changes. This makes documenting them
required.
---
 DOCS/compatibility.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/DOCS/compatibility.rst b/DOCS/compatibility.rst
index fb54a19aec..aeef8fc7ca 100644
--- a/DOCS/compatibility.rst
+++ b/DOCS/compatibility.rst
@@ -29,6 +29,13 @@ 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.
 
+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.