Deprecating (and deleting) user-facing APIs [was Re: Why do functions objfpy_new and pspy_new exist?]

Deprecating (and deleting) user-facing APIs [was Re: Why do functions objfpy_new and pspy_new exist?]

[Doug Evans]

[I've changed the subject line to make the topic stand out more ...]

On Thu, Oct 2, 2014 at 3:11 PM, Stan Shebs <stanshebs@earthlink.net> wrote:
> On 9/25/14, 3:07 PM, Doug Evans wrote:
> [...]
>>
>> I know I've mentioned this before, but since the topic has come up again,
>> I think GDB could have a formal deprecation process that would allow
>> us to remove things we'd like to remove (this is for API-like things
>> which are harder to remove than, e.g., outdated ports).
>
> Nominally, the existing process is as described at
>
> https://sourceware.org/gdb/wiki/Internals%20Obsoleting-code
>
> We've also done "deprecate in one release, remove in the next", and
> added "deprecated_" onto function names and such.  Empirically, it
> hasn't created the desired urgency - people have been content to keep
> calling deprecated_foo for many years after its deprecation. :-)

Yeah, though this situation is different in the sense that the subject
here is externally facing APIs.
At least different from adding "deprecated_" to function names;
if we rename a function we've already broken user code.
[One can imagine a multistep process where we add deprecated_foo as a
synonym for foo,
then later delete foo, and then still later delete deprecated_foo.
That might be overkill in general.]

I'm glad I haven't seen any real pushback (at least not yet :-)),
so to advance the discussion ...

One thing I think we need is to publish somewhere the state
of the things being deprecated (and by "things" here I mean only
user-facing API elements).
[I'd still document the process for developers to follow in the above link.
What I'm talking about here is for users to see the details of
what's currently in the process of being deprecated/deleted.]

And by "deprecated" here I also mean that we intend to eventually
delete it.  Anything deprecated here is also given a deletion date
(where the date is probably expressed in terms of number of releases from now).

We want to give users time to migrate away from things that
will eventually be deleted, and I can imagine the length of time
being more than one release.  Thus we need to publish
the current state in a place where users can find it and track it.
I don't have a strong opinion on where this documentation lives.
Anyone have a strong opinion on where this should live?
I can see an argument made for keeping it with the sources.
As a strawman we could have a "Deprecated APIs" section in gdb.texinfo.
I would also add an easy to find link to the currently generated form
from the website.
I'd also add appropriate entries to NEWS of course.

Comments?

Re: Deprecating (and deleting) user-facing APIs [was Re: Why do functions objfpy_new and pspy_new exist?]

[Phil Muldoon]

On 09/10/14 19:07, Doug Evans wrote:
> (where the date is probably expressed in terms of number of releases from now). We want to give users time to migrate away from things that will eventually be deleted, and I can imagine the length of time being more than one release. Thus we need to publish the current state in a place where users can find it and track it. I don't have a strong opinion on where this documentation lives. Anyone have a strong opinion on where this should live? I can see an argument made for keeping it with the sources. As a strawman we could have a "Deprecated APIs" section in gdb.texinfo. I would also add an easy to find link to the currently generated form from the website. I'd also add appropriate entries to NEWS of course. Comments?


I think it should live:

1) In the code comments.
2) In any user facing documentation, both the manual and any printed
   help
3) Maybe on the wiki too.

I agree with the NEWS file.  Also with the manual, if we have a
deprecated API section, I think it should be bound to the section it
refers to (IE Python has its own deprecated section).  We can link all
of these together in one master list or something.

While we are here pondering these, I would also like to bring up
deprecating versions of Python.  It has become a difficult and time
consuming chore at review time (and at release time) to ensure that we
support as many Python versions as we do.  Python 2.x and Python 3.x
are moving ever further apart in an incompatible way.  The amount of
people working on the Python support, along with their other duties (I
have been tied up with the GDB compile and inject support deeply over
the last six months) really is insufficient.  It will only get worse I
think.  The time I do have goes into checking reviews and any code I
write works across the Python board.  Time that could be spent
elsewhere on newer features.

So let me propose something.  From GDB 8 on-wards, lets only support
Python 3.x.  If this is too early, maybe 8.1 or 8.2. Anyway, we
message this consistently and continuously to the community. Document
it in all the right high traffic places.  What do folks think?

Cheers,

Phil

PS, Sorry Doug, on reading back it looks like I might have hijacked or
slightly segued your original topic! But all of this stuff is tied
together.

Re: Deprecating (and deleting) user-facing APIs [was Re: Why do functions objfpy_new and pspy_new exist?]

[Eli Zaretskii]

> Date: Fri, 10 Oct 2014 08:37:36 +0100
> From: Phil Muldoon <pmuldoon@redhat.com>
> CC: gdb-patches <gdb-patches@sourceware.org>
> 
> So let me propose something.  From GDB 8 on-wards, lets only support
> Python 3.x.  If this is too early, maybe 8.1 or 8.2. Anyway, we
> message this consistently and continuously to the community. Document
> it in all the right high traffic places.  What do folks think?

No, please don't unsupport Python 2.x, not yet.  I'm still using
Python 2.x based applications (e.g., bzr), and I'd like to avoid
having 2 different versions of Python on the same machine, if
possible.

Re: Deprecating (and deleting) user-facing APIs [was Re: Why do functions objfpy_new and pspy_new exist?]

[Phil Muldoon]

On 10/10/14 08:50, Eli Zaretskii wrote:
>> Date: Fri, 10 Oct 2014 08:37:36 +0100
>> From: Phil Muldoon <pmuldoon@redhat.com>
>> CC: gdb-patches <gdb-patches@sourceware.org>
>>
>> So let me propose something.  From GDB 8 on-wards, lets only support
>> Python 3.x.  If this is too early, maybe 8.1 or 8.2. Anyway, we
>> message this consistently and continuously to the community. Document
>> it in all the right high traffic places.  What do folks think?
>
> No, please don't unsupport Python 2.x, not yet.  I'm still using
> Python 2.x based applications (e.g., bzr), and I'd like to avoid
> having 2 different versions of Python on the same machine, if
> possible.

I expect some push back from distro maintainers too. So this feedback
is all good; it might be that logistically for our users this might
not be possible at all. So that is what I would really love to hear -
thanks for letting me (and GDB) know.

However, 8.2 is quite far off.  Do you know of any plans in the future
for your distro to support two Python versions or switch to 3?  FWIW
later versions of Fedora supports both Pythons, and I think (though I
cannot find the link right now), have plans to move entirely to Python
3.

Anyway, thanks for the feedback.  I do realize this might be a case of
sharing GDB Python developers' pain with others a little.

Cheers

Phil

Re: Deprecating (and deleting) user-facing APIs [was Re: Why do functions objfpy_new and pspy_new exist?]

[Eli Zaretskii]

> Date: Fri, 10 Oct 2014 09:07:42 +0100
> From: Phil Muldoon <pmuldoon@redhat.com>
> CC: dje@google.com, stanshebs@earthlink.net, gdb-patches@sourceware.org
> 
> Do you know of any plans in the future for your distro to support
> two Python versions or switch to 3?

No.  At least bzr is no longer being developed, so it is hard to
imagine it will switch.  But AFAIK Ubuntu uses bzr as its main VCS, so
until and unless that changes, at least Ubuntu users will probably
have Python 2.x.

Re: Deprecating (and deleting) user-facing APIs [was Re: Why do functions objfpy_new and pspy_new exist?]

[Doug Evans]

On Fri, Oct 10, 2014 at 12:37 AM, Phil Muldoon <pmuldoon@redhat.com> wrote:
> On 09/10/14 19:07, Doug Evans wrote:
>> (where the date is probably expressed in terms of number of releases from now). We want to give users time to migrate away from things that will eventually be deleted, and I can imagine the length of time being more than one release. Thus we need to publish the current state in a place where users can find it and track it. I don't have a strong opinion on where this documentation lives. Anyone have a strong opinion on where this should live? I can see an argument made for keeping it with the sources. As a strawman we could have a "Deprecated APIs" section in gdb.texinfo. I would also add an easy to find link to the currently generated form from the website. I'd also add appropriate entries to NEWS of course. Comments?
>
>
> I think it should live:
>
> 1) In the code comments.
> 2) In any user facing documentation, both the manual and any printed
>    help
> 3) Maybe on the wiki too.

It's important that this stuff stay up to date and in sync.
I'm ok with a link on the wiki to the generated html form of the docs,
but I'm uncomfortable with having the data appear in multiple places.

> I agree with the NEWS file.  Also with the manual, if we have a
> deprecated API section, I think it should be bound to the section it
> refers to (IE Python has its own deprecated section).  We can link all
> of these together in one master list or something.
>
> While we are here pondering these, I would also like to bring up
> deprecating versions of Python.  It has become a difficult and time
> consuming chore at review time (and at release time) to ensure that we
> support as many Python versions as we do.  Python 2.x and Python 3.x
> are moving ever further apart in an incompatible way.  The amount of
> people working on the Python support, along with their other duties (I
> have been tied up with the GDB compile and inject support deeply over
> the last six months) really is insufficient.  It will only get worse I
> think.  The time I do have goes into checking reviews and any code I
> write works across the Python board.  Time that could be spent
> elsewhere on newer features.

Yeah.  I think we'll need 2.x for awhile, but it's certainly desirable
to require 2.7, and deprecate/delete support for everything prior.

>
> So let me propose something.  From GDB 8 on-wards, lets only support
> Python 3.x.  If this is too early, maybe 8.1 or 8.2. Anyway, we
> message this consistently and continuously to the community. Document
> it in all the right high traffic places.  What do folks think?
>
> Cheers,
>
> Phil
>
> PS, Sorry Doug, on reading back it looks like I might have hijacked or
> slightly segued your original topic! But all of this stuff is tied
> together.

No worries.