DOCS: add more details and requirements about incompatible changes #14156
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Currently incompatible changes are not clearly outlined in the related documentations, such as interface-changes.rst. The impacts and suggested actions to address the compatibility concerns also rarely exist. This adds a requirement to include these information for incompatible changes, so that such changes are clearly conveyed to the users, with suggested actions to minimize the impacts of such changes.
na-na-hi
force-pushed
the
docs-compatibility
branch
3 times, most recently
from
4dcf4bf
to
d85f96b
Compare
Akemi
approved these changes
May 16, 2024
sunpenghao
reviewed
May 17, 2024
Currently there is no policy on what should be done when an immediate, severe breakage happens for "important/often used parts", which can cause serious concerns especially if such changes remain obscured. This adds a provision for this kind of incompatible changes under "extraordinary circumstances", which allows for the breaking change to happen if there is a critical reason to do so. Such changes must be extensively documented, and should be avoided as much as possible.
Documented default values are relied upon by scripts, so changing these values can casuse incompatible changes. This makes documenting them required.
The default values for --ao, --vo, --gpu-api, --gpu-context change from time to time, but some libmpv clients rely on the existing autoprobe order and breaks as a result when the value changes. This specifies that the default autoprobe order should not be relied upon.
na-na-hi
force-pushed
the
docs-compatibility
branch
from
d85f96b
to
2872bf9
Compare
As an instance of "extraordinary circumstances", such incompatibility must be extensively documented.
na-na-hi
force-pushed
the
docs-compatibility
branch
from
2872bf9
to
f2a932f
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There is clearly not enough being conveyed about the incompatible changes happened, and users are left guessing what should be done after that. This PR adds these details and requirements so that these concerns are clearly conveyed to the users so that breaking changes can be handled swiftly.
See also #13974.