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

[Doug Evans <dje at google dot com>]

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.