Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney <cagney at gnu dot org>]

> Per Andrew Cagney's request, I am reposting here a message I sent on
> gdb-patches after a long discussion between Andrew and Eli Zaretskii
> on when parts of GDB's code can be marked as deprecated and how they
> should be marked as deprecated.
>
> Andrew also asked me to post Eli's answer, but I can't find it in
> the archives. Sorry Eli, you'll have to resend them.

Over the years GDB's evolved three related processes for addressing the 
problem of old or dead code:

- deprecate
- obsolete
- garbage collect
- end-of-life

each serves a purpose (but only the middle one is currently documented).

- deprecate

This is a flagging mechanisms (namely for interfaces).  It doesn't come 
with any time table and hence there's no exit strategy for their 
elimination.

This mechanism has proved extreemly effective, in particular in 
addressing the problem of contributors trying to add new, but largely 
self contained, components such as architectures needing to know what is 
in and what is out.  It's taken away the oportunity to flip-flop over 
what can and can not be used by such a contribution.

- obsolete

This was introduced during multi-arch and went with a long and bloody 
battle - there was much debate over the relative merits of removing old 
code (rather than retaining it "just in case").  It was so that we could 
could remove old targets and architectures that were being identified as 
multi-arch was progressing.

- garbage collect

While different people use different names, the principle is the same - 
if it's no longer reachable, it can be removed.

- end-of-life

GDB 6.2 saw the old frame code reaching its end of life.  It let us 
remove a huge chunk code propping up old, and clearly unmaintained 
architectures.  GDB 6.3 will do similar with deprecated_registers[].

With out this we'd have been forced to support those old architectures 
indefinitly.

> > > It seems to me that the whole discussion between Eli and yourself has
> > > been beaten to death. We're basically stuck in a disagrement where both
> > > point of views have their merit.
> > >
> > > I think it's time all global maintainers get involved in this discussion
> > > and make a decision. Once the decision is taken, it needs to be
> > > documented (gdb.texinfo for instance) so that people can refer to it.
> > >
> > > As a developper, I personally dislike to have to check the ARI everytime
> > > I use anything in GDB for fear of using something deprecated. So marking
> > > each instance as explicitly deprecated directly in the code is a good
> > > move. Two questions were asked and need to be answered. I am adding my
> > > proposed answers, as a starting point for your discussion:
> > >
> > >  1. When can some code be declared deprecated?
> > >
> > >     IMO, some code should be declared deprecated when it has been
> > >     recognized that it should no longer be used in new changes.
> > >     It means that some code can be identified as deprecated before
> > >     a replacement has been implemented.

> > >     There is a judgement call to make, obviously, as we don't want to
> > >     deprecate a central piece of GDB that makes it impossible for
> > >     somebody to submit a new port for instance without doing man-years
> > >     of work required to implement an alternate to the deprecated
> > >     feature.

Right.

In general though the basic mechanism is implemented and demonstrated.

> > >  2. How to identify deprecated code?
> > >
> > >     Deprecated code should be explicitly marked as such directly
> > >     in the code, to avoid any accidental future usage, by prepending
> > >     "depreated_" to the entity names.
> > >     
> > >     Deprecated code can only be removed when no longer used. There can
> > >     be no time limit imposed between the time some code is deprecated,
> > >     and the time when it is removed.
> > >
> > >     (the alternate solution suggested by Eli is the ARI)

Right.

I think it is important that we all remember that this mechanism is 
strictly internal (to the user, nothing is visible) and in no way is 
ment to demean a specific architecture, system, or developer concerned 
with that area.  We should be careful to not interpret it as such.

Working through Eli's reply ...

> >   1. When can some code be declared deprecated?
> >
> >      IMO, some code should be declared deprecated when it has been
> >      recognized that it should no longer be used in new changes.
> >      It means that some code can be identified as deprecated before
> >      a replacement has been implemented.
>
> "Identified as deprecated" and "declared deprecated" need not happen
> at the same time.  That time might (and IMHO should) be used to
> implement the replacement.
>
> >      There is a judgement call to make, obviously, as we don't want to
> >      deprecate a central piece of GDB that makes it impossible for
> >      somebody to submit a new port for instance without doing man-years
> >      of work required to implement an alternate to the deprecated
> >      feature.
>
> I note that you didn't suggest any way out of this contradiction.  I
> did suggest such a way: implement and commit the alternate mechanism
> before or together with the patch that marks the old code deprecated.

We went through a very much the same debate with obsolete:

- should we blindly convert the obsolete code to new mechanisms

- or should we leave that task for someone with both the motivation to 
take on the challenge and the facilities to test it

we choose the latter, and with good reason.

- any blindly converted mechanism wasn't tested and didn't work - wasted 
effort

- we can't be requireing contributors to be expected to maintan/fix each 
and every system when many of those same systems have no relevance 
(think many of the more obscure architectures or targets)

In theory deprecation should be initiated by the relevant maintaner - 
arch, targ, symtab - but here reality is that I do it.  The process is 
that they are posted one week and committed the next which gives plenty 
of time for objection (and we've seen a few of them).

We should document this.

> >   2. How to identify deprecated code?
> >
> >      Deprecated code should be explicitly marked as such directly
> >      in the code, to avoid any accidental future usage, by prepending
> >      "depreated_" to the entity names.
>
> This doesn't ensure that accidental future use is avoided, because not
> all contributors have the latest CVS before their eyes when they work
> on their contribution.

There are rarely absolutes.

On the other hand this mechansm has proven its self very effective. 
People contributing new architectures, natives and systems are very 
aware of the expectation that they can't use deprecated mechanisms. 
People maintaining existing architectures et.al. are equally aware of 
this and they too focus on the need to get things updated.

> A requirement that everything important for the contributor to get
> his/her code right the first time be in the code is IMHO ridiculous:
> it will, for example, cause us to spill a large part of gdbint.texinfo
> into the sources, as well as the contents of MAINTAINERS and PROBLEMS.
>
> The correct (IMHO) way out of this predicament is to request that
> contributors read all the relevant pieces of code and documentation
> (if they don't know, they can ask where to look).  Of course, this
> doesn't eliminate a possibility that they will overlook, but I'm not
> aware of any project that avoided that with a 100% insurance; I don't
> see why this should be such a great deal here.

We're programmers.  We speak through the code.  The internals document 
has its place, but the bottom line is that the code and not the 
internals document determines how GDB works.  Hence, that is what 
programmers read.

> More generally, AFAIR the "depreated_" stunt was invented mainly as an
> aid to the maintainer(s): to make their job easier when they want to
> know what stuff is candidate for deletion.  It is a bit funny to see
> this convenience trick sudenly being inflated with so much ideology.

Who's recollection?

Real deprecation started with multi-arch in '98 (your first post was in 
'99) vs:

- as architecture macro's were were replaced by architecture methods the 
old macros were deprecated.

- as old poorly designed architecture-interfaces were re-implemented 
(allowing us to fix long standing bugs) the old were deprecated.

- as redundant architecture methods were identified, they were deprecated.

Yes, it did make my job easier - I didn't have to chase after people 
constantly reminding them that the're using deprecated methods and plead 
with them not to.

This effort has been been going on for years, it's hardly a stunt.

Andrew