Just FYI I've already pushed these patches, but I appreciate the comments anyway. Quoting Stefano Sabatini (2023-03-20 23:26:11)
On date Wednesday 2023-03-15 15:07:46 +0100, Anton Khirnov wrote:
Document established practices in it. --- doc/developer.texi | 162 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 146 insertions(+), 16 deletions(-)
diff --git a/doc/developer.texi b/doc/developer.texi index 5e283227be..c625a9feed 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -217,6 +217,7 @@ int myfunc(int my_parameter) ... @end example
+@anchor{Naming conventions} @section Naming conventions [...] + +@anchor{Major version bumps} +@subsection Major version bumps +A major version bump signifies an API and/or ABI compatibility break. To reduce +the negative effects on our callers, who are required to adapt their code, +backward-incompatible changes during a major bump should be limited to: +@itemize @bullet +@item +Removing previously deprecated APIs. + +@item +Performing ABI- but not API-breaking changes, like reordering struct contents. +@end itemize +
This sounds a bit ambiguous. What qualifies "previously deprecated APIs"? It looks to me that the current practice is to drop deprecated symbols after 2 major bumps, so that users have the opportunity to adapt their code depending on the deprecations warnings before the deprecated symbols are finally removed at the next bump. If that's so, maybe this can be formalized here.
The ambiguity is actually deliberate, because I know different developers have different opinions on what the criterium should be exactly, and I did not want this whole new text to be bikeshud to death because of this. My plan was to push this text with ambiguous wording, and then later add a precise rule. The previous "consensus rule" was to remove APIs after they've been deprecated for two yeas, but in recent developer meetings it was universally agreed that time-based rules do not make sense. The main alternative suggestions that I remember is that a major bump removes things that were deprecated in X previous major releases (I'm personally in favor of this with X=2). Other suggestions, along with arguments for why they are the obviously correct choice, are very much welcome. -- Anton Khirnov