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

[Doug Evans <dje at google dot com>]

[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?