From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 7E66C456E8 for ; Tue, 21 Mar 2023 08:10:30 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 2FAD168C67C; Tue, 21 Mar 2023 10:10:28 +0200 (EET) Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id A1C5568B97D for ; Tue, 21 Mar 2023 10:10:21 +0200 (EET) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id 333A52404EA for ; Tue, 21 Mar 2023 09:10:20 +0100 (CET) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id IctjO-7iX_xt for ; Tue, 21 Mar 2023 09:10:19 +0100 (CET) Received: from lain.khirnov.net (lain.khirnov.net [IPv6:2001:67c:1138:4306::3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "lain.khirnov.net", Issuer "smtp.khirnov.net SMTP CA" (verified OK)) by mail0.khirnov.net (Postfix) with ESMTPS id 6E4DB240178 for ; Tue, 21 Mar 2023 09:10:19 +0100 (CET) Received: by lain.khirnov.net (Postfix, from userid 1000) id 4DDEB1601B2; Tue, 21 Mar 2023 09:10:19 +0100 (CET) From: Anton Khirnov To: FFmpeg development discussions and patches In-Reply-To: <20230320222611.GI48946@mariano> References: <20230315140746.14692-1-anton@khirnov.net> <20230315140746.14692-3-anton@khirnov.net> <20230320222611.GI48946@mariano> Mail-Followup-To: FFmpeg development discussions and patches Date: Tue, 21 Mar 2023 09:10:19 +0100 Message-ID: <167938621928.27013.15093722917572734217@lain.khirnov.net> User-Agent: alot/0.8.1 MIME-Version: 1.0 Subject: Re: [FFmpeg-devel] [PATCH 3/3] doc/developer.texi: add a section on API/ABI compatibility X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: 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 _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".