[FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Anton Khirnov]

Previously, the implicit standard was to wait 2 years before deprecation
and removal, but it has been widely agreed at developer meetings that
time-based measures do not make sense and we should switch to a
release-based one instead.
---
Feel welcome to argue for other numbers than 2, or suggest alternative
criteria, but please try to limit bikeshedding.
---
 doc/developer.texi | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index dd96e3b36a..3f3218f66a 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -552,7 +552,8 @@ 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.
+Removing APIs that were marked as deprecated in at least two previous
+major releases.
 
 @item
 Performing ABI- but not API-breaking changes, like reordering struct contents.
-- 
2.42.0

_______________________________________________
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".

Re: [FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Michael Niedermayer]

[-- Attachment #1.1: Type: text/plain, Size: 1489 bytes --]

On Sun, Jan 28, 2024 at 01:28:36PM +0100, Anton Khirnov wrote:
> Previously, the implicit standard was to wait 2 years before deprecation
> and removal, but it has been widely agreed at developer meetings that
> time-based measures do not make sense and we should switch to a
> release-based one instead.
> ---
> Feel welcome to argue for other numbers than 2, or suggest alternative
> criteria, but please try to limit bikeshedding.
> ---
>  doc/developer.texi | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/developer.texi b/doc/developer.texi
> index dd96e3b36a..3f3218f66a 100644
> --- a/doc/developer.texi
> +++ b/doc/developer.texi
> @@ -552,7 +552,8 @@ 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.
> +Removing APIs that were marked as deprecated in at least two previous
> +major releases.

Removing APIs that were marked as deprecated in at least two previous
major releases for at least 1 year.

(goal of this proposed difference is to ensure that if for whatever reason
 we make several major releases in quick succession it doesnt deprecate
 things faster)

thx

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

Everything should be made as simple as possible, but not simpler.
-- Albert Einstein

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

[-- Attachment #2: Type: text/plain, Size: 251 bytes --]

_______________________________________________
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".

Re: [FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Vittorio Giovara]

On Sun, Jan 28, 2024 at 11:47 PM Michael Niedermayer <michael@niedermayer.cc>
wrote:

> On Sun, Jan 28, 2024 at 01:28:36PM +0100, Anton Khirnov wrote:
> > Previously, the implicit standard was to wait 2 years before deprecation
> > and removal, but it has been widely agreed at developer meetings that
> > time-based measures do not make sense and we should switch to a
> > release-based one instead.
> > ---
> > Feel welcome to argue for other numbers than 2, or suggest alternative
> > criteria, but please try to limit bikeshedding.
> > ---
> >  doc/developer.texi | 3 ++-
> >  1 file changed, 2 insertions(+), 1 deletion(-)
> >
> > diff --git a/doc/developer.texi b/doc/developer.texi
> > index dd96e3b36a..3f3218f66a 100644
> > --- a/doc/developer.texi
> > +++ b/doc/developer.texi
> > @@ -552,7 +552,8 @@ 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.
> > +Removing APIs that were marked as deprecated in at least two previous
> > +major releases.
>
> Removing APIs that were marked as deprecated in at least two previous
> major releases for at least 1 year.
>
> (goal of this proposed difference is to ensure that if for whatever reason
>  we make several major releases in quick succession it doesnt deprecate
>  things faster)
>

IMO that's a bit verbose and given language is not precise it could lead to
confusion (at least 1 year from deprecation? from a release with a
deprecation warning? a mix of the two?)
I find extremely unlikely that there will be two major releases, and these
are supposed to be guidelines so I'm sure that even in that event we could
reasonably delay things if needed
-- 
Vittorio
_______________________________________________
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".

Re: [FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Michael Niedermayer]

[-- Attachment #1.1: Type: text/plain, Size: 2183 bytes --]

On Mon, Jan 29, 2024 at 10:31:02AM +0100, Vittorio Giovara wrote:
> On Sun, Jan 28, 2024 at 11:47 PM Michael Niedermayer <michael@niedermayer.cc>
> wrote:
> 
> > On Sun, Jan 28, 2024 at 01:28:36PM +0100, Anton Khirnov wrote:
> > > Previously, the implicit standard was to wait 2 years before deprecation
> > > and removal, but it has been widely agreed at developer meetings that
> > > time-based measures do not make sense and we should switch to a
> > > release-based one instead.
> > > ---
> > > Feel welcome to argue for other numbers than 2, or suggest alternative
> > > criteria, but please try to limit bikeshedding.
> > > ---
> > >  doc/developer.texi | 3 ++-
> > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/doc/developer.texi b/doc/developer.texi
> > > index dd96e3b36a..3f3218f66a 100644
> > > --- a/doc/developer.texi
> > > +++ b/doc/developer.texi
> > > @@ -552,7 +552,8 @@ 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.
> > > +Removing APIs that were marked as deprecated in at least two previous
> > > +major releases.
> >
> > Removing APIs that were marked as deprecated in at least two previous
> > major releases for at least 1 year.
> >
> > (goal of this proposed difference is to ensure that if for whatever reason
> >  we make several major releases in quick succession it doesnt deprecate
> >  things faster)
> >
> 
> IMO that's a bit verbose and given language is not precise it could lead to
> confusion (at least 1 year from deprecation? from a release with a
> deprecation warning? a mix of the two?)

You can suggest clearer language.

The advanagte of including a time period is that its easier for people
to plan things, as they know how long they can depend on an API.

thx

[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

I know you won't believe me, but the highest form of Human Excellence is
to question oneself and others. -- Socrates

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

[-- Attachment #2: Type: text/plain, Size: 251 bytes --]

_______________________________________________
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".

Re: [FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Anton Khirnov]

Quoting Michael Niedermayer (2024-01-28 23:47:06)
> On Sun, Jan 28, 2024 at 01:28:36PM +0100, Anton Khirnov wrote:
> > Previously, the implicit standard was to wait 2 years before deprecation
> > and removal, but it has been widely agreed at developer meetings that
> > time-based measures do not make sense and we should switch to a
> > release-based one instead.
> > ---
> > Feel welcome to argue for other numbers than 2, or suggest alternative
> > criteria, but please try to limit bikeshedding.
> > ---
> >  doc/developer.texi | 3 ++-
> >  1 file changed, 2 insertions(+), 1 deletion(-)
> > 
> > diff --git a/doc/developer.texi b/doc/developer.texi
> > index dd96e3b36a..3f3218f66a 100644
> > --- a/doc/developer.texi
> > +++ b/doc/developer.texi
> > @@ -552,7 +552,8 @@ 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.
> > +Removing APIs that were marked as deprecated in at least two previous
> > +major releases.
> 
> Removing APIs that were marked as deprecated in at least two previous
> major releases for at least 1 year.
> 
> (goal of this proposed difference is to ensure that if for whatever reason
>  we make several major releases in quick succession it doesnt deprecate
>  things faster)

I don't think it is a good idea, because experience shows that our users
update either very quickly (within a few months), or wait until their
hand is forced by the API being removed. I find it extremely unlikely
that we'll need to have three major releases within a few months, so
this rule would serve no useful purpose. It could, however, have a
negative effect in delaying the bump and the subsequent release until we
reach the exact one year mark. I don't think we need any extra delays in
our release process.

-- 
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".

Re: [FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Andrew Randrianasulu]

пн, 29 янв. 2024 г., 13:55 Anton Khirnov <anton@khirnov.net>:

> Quoting Michael Niedermayer (2024-01-28 23:47:06)
> > On Sun, Jan 28, 2024 at 01:28:36PM +0100, Anton Khirnov wrote:
> > > Previously, the implicit standard was to wait 2 years before
> deprecation
> > > and removal, but it has been widely agreed at developer meetings that
> > > time-based measures do not make sense and we should switch to a
> > > release-based one instead.
> > > ---
> > > Feel welcome to argue for other numbers than 2, or suggest alternative
> > > criteria, but please try to limit bikeshedding.
> > > ---
> > >  doc/developer.texi | 3 ++-
> > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/doc/developer.texi b/doc/developer.texi
> > > index dd96e3b36a..3f3218f66a 100644
> > > --- a/doc/developer.texi
> > > +++ b/doc/developer.texi
> > > @@ -552,7 +552,8 @@ 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.
> > > +Removing APIs that were marked as deprecated in at least two previous
> > > +major releases.
> >
> > Removing APIs that were marked as deprecated in at least two previous
> > major releases for at least 1 year.
> >
> > (goal of this proposed difference is to ensure that if for whatever
> reason
> >  we make several major releases in quick succession it doesnt deprecate
> >  things faster)
>
> I don't think it is a good idea, because experience shows that our users
> update either very quickly (within a few months), or wait until their
> hand is forced by the API being removed.



Just for the record: I dislike when ffmpeg breaks it for us. You may call
me incompetent, but then I'll invite you to work voluntary as maintainer of
cinelerra-gg.


I find it extremely unlikely
> that we'll need to have three major releases within a few months, so
> this rule would serve no useful purpose. It could, however, have a
> negative effect in delaying the bump and the subsequent release until we
> reach the exact one year mark. I don't think we need any extra delays in
> our release process.
>
> --
> 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".
>
_______________________________________________
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".

Re: [FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Michael Niedermayer]

[-- Attachment #1.1: Type: text/plain, Size: 2899 bytes --]

On Mon, Jan 29, 2024 at 02:20:00PM +0300, Andrew Randrianasulu wrote:
> пн, 29 янв. 2024 г., 13:55 Anton Khirnov <anton@khirnov.net>:
> 
> > Quoting Michael Niedermayer (2024-01-28 23:47:06)
> > > On Sun, Jan 28, 2024 at 01:28:36PM +0100, Anton Khirnov wrote:
> > > > Previously, the implicit standard was to wait 2 years before
> > deprecation
> > > > and removal, but it has been widely agreed at developer meetings that
> > > > time-based measures do not make sense and we should switch to a
> > > > release-based one instead.
> > > > ---
> > > > Feel welcome to argue for other numbers than 2, or suggest alternative
> > > > criteria, but please try to limit bikeshedding.
> > > > ---
> > > >  doc/developer.texi | 3 ++-
> > > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > > >
> > > > diff --git a/doc/developer.texi b/doc/developer.texi
> > > > index dd96e3b36a..3f3218f66a 100644
> > > > --- a/doc/developer.texi
> > > > +++ b/doc/developer.texi
> > > > @@ -552,7 +552,8 @@ 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.
> > > > +Removing APIs that were marked as deprecated in at least two previous
> > > > +major releases.
> > >
> > > Removing APIs that were marked as deprecated in at least two previous
> > > major releases for at least 1 year.
> > >
> > > (goal of this proposed difference is to ensure that if for whatever
> > reason
> > >  we make several major releases in quick succession it doesnt deprecate
> > >  things faster)
> >
> > I don't think it is a good idea, because experience shows that our users
> > update either very quickly (within a few months), or wait until their
> > hand is forced by the API being removed.
> 
> 
> 
> Just for the record: I dislike when ffmpeg breaks it for us. You may call
> me incompetent, but then I'll invite you to work voluntary as maintainer of
> cinelerra-gg.

I also have always advocated longer support for APIs/ABIs but many developers
who work on cleanups prefer shorter periods which is understandable too

Personally i would also favour if APIs/ABIs are only removed when keeping them
causes work. Often old API/ABI just needs a simple wraper around new API that
has no dependancy on anything else than the new API working as documented.

In other cases where there is risk that API/ABI might break in ways not readily
detectable, quick removial makes sense though

thx

[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

Concerning the gods, I have no means of knowing whether they exist or not
or of what sort they may be, because of the obscurity of the subject, and
the brevity of human life -- Protagoras

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

[-- Attachment #2: Type: text/plain, Size: 251 bytes --]

_______________________________________________
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".

Re: [FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Anton Khirnov]

Quoting Andrew Randrianasulu (2024-01-29 12:20:00)
> пн, 29 янв. 2024 г., 13:55 Anton Khirnov <anton@khirnov.net>:
> 
> > Quoting Michael Niedermayer (2024-01-28 23:47:06)
> > > On Sun, Jan 28, 2024 at 01:28:36PM +0100, Anton Khirnov wrote:
> > > > Previously, the implicit standard was to wait 2 years before
> > deprecation
> > > > and removal, but it has been widely agreed at developer meetings that
> > > > time-based measures do not make sense and we should switch to a
> > > > release-based one instead.
> > > > ---
> > > > Feel welcome to argue for other numbers than 2, or suggest alternative
> > > > criteria, but please try to limit bikeshedding.
> > > > ---
> > > >  doc/developer.texi | 3 ++-
> > > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > > >
> > > > diff --git a/doc/developer.texi b/doc/developer.texi
> > > > index dd96e3b36a..3f3218f66a 100644
> > > > --- a/doc/developer.texi
> > > > +++ b/doc/developer.texi
> > > > @@ -552,7 +552,8 @@ 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.
> > > > +Removing APIs that were marked as deprecated in at least two previous
> > > > +major releases.
> > >
> > > Removing APIs that were marked as deprecated in at least two previous
> > > major releases for at least 1 year.
> > >
> > > (goal of this proposed difference is to ensure that if for whatever
> > reason
> > >  we make several major releases in quick succession it doesnt deprecate
> > >  things faster)
> >
> > I don't think it is a good idea, because experience shows that our users
> > update either very quickly (within a few months), or wait until their
> > hand is forced by the API being removed.
> 
> 
> 
> Just for the record: I dislike when ffmpeg breaks it for us. You may call
> me incompetent, but then I'll invite you to work voluntary as maintainer of
> cinelerra-gg.

We know that API breaks are a burden for users, but they are necessary.
We don't break API just for fun.

And the point of this thread is not whether we should have API breaks at
all, but how long to keep deprecated APIs.

-- 
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".