Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney <cagney at gnu dot org>]

> > > Date: Wed, 06 Oct 2004 01:08:13 -0400
> > > From: Andrew Cagney <cagney@gnu.org>
> > > Cc: gdb@sources.redhat.com, Andrew Cagney <cagney@redhat.com>
>
>
> Andrew, thank you for an informative message.
>
> Unfortunately, it doesn't help in making a progress in this
> discussion, since all it does is reiterate your opinions that were
> clear (at least to me) during the XM_FILE debate, or else explaining
> principles and generalities that don't need to be explained.

> I'm fully aware that you, and at least some of the other maintainers,
> are eager to deprecate and remove code that you think is not
> maintained quickly enough for your liking.  It is probably not news to
> you that I don't like that eagerness; we had enough discussions in the
> past along those lines, and I didn't make a secret out of my views.  I
> think such tendencies are harsh on the users and on sysadmins (in
> fact, they are harsh on everybody but GDB developers), and are not at
> all justified by the added maintenance burden they are allegedly
> supposed to magically remove.

I can only guess or suspect.  E-mail being a primative medium doesn't 
let us read between the lines and identify when there's an underlying 
issue.  Here we've again made progress, we've gone from XM_FILE, to 
deprecation, to the agressive removal of code.   What of the overall 
rate of change, and release cycles, ...?  This is also why I've been 
stating principals and generalities - trying to figure out what the 
underlying issue is.

"deprecation", since it is all internal, is hardest on the developers 
yet many are the ones expressing a certain appreciation.

The "users" I interact with appreciate the more timely releases that 
give them faster acces to fixes, so I don't know what is "harsh" here. 
Can you explain?

> So saying once again that you don't want to request patch contributors
> (which is mostly yourself in the case of "deprecated_" stuff) to fix
> the affected portions of the code as a perequisite for accepting the
> patch, and that you don't want to maintain obsolete code, does not
> change anything in what is already known as a serious disagreement.
> If that is all we can say, let's just agree to disagree, and be done
> with that.
>
> If you do want to try to convince me, you (or someone else who thinks
> like you) will have to do better than that.

Now that cuts both ways, you've not convinced anyone either :-(

> > > 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.
>
>
> I'm not sure what is it that you are saying here.  Should we abandon
> gdbint.texinfo and instead rely on the code to explain itself, because
> ``we are programmers and thus code is the only thing we read''?  Maybe
> I should stop trying so hard to review each documentation patch in a
> matter of days, because the code already says all there is to tell?

[Sarcasm] Obviously, that's why I'm spending part of my time on 
internals documentation.

> I agree with the principle that we should draw a line somewhere
> between the part of the documentation that should go into a manual and
> the part that should stay in the code, so the argument is not over the
> principle.  I hope you will agree that, in principle, _some_
> information _can_ be put in a manual, because otherwise I don't
> understand why you just pinged me to review your gdbint patches about
> branching and versioning; why not have that as comments to version.in,
> for example?

> The issue at hand is not the principle, but rather my very specific
> suggestion that the fact some code or method is deprecated could be
> stated in the manual.  If you object to that specific suggestion,
> please back up your opinion by specific arguments, not by reiterating
> abstract principles to which we all agree.

The internals documentation should contain the process, or the overview. 
 The code, the specifics.  Unless of course I get around to doing to 
gdbarch.sh what I did for the observers (i.e., single source in 
observer.texi).

> > > Real deprecation started with multi-arch in '98 (your first post was in 
> > > '99)
>
>
> What does the date of my first post have to do with the issue at hand?
> Isn't it possible that I've also read the archives, even beyond the
> days I started to be an active GDB maintainer?

You wrote:

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

Besides being a slur, I find it really troubling that you've somehow 
become convinced of this.  Back in '98 and '99, all significant 
technical discussion, and all technical decisions,  were being made on 
cynus-internal mailing lists and in cygnus-internal meetings (It wasn't 
until '00 that things really improved) :-(  Beyond the ChangeLogs 
there's little (other than hearsay) to go by.

Looking in 4.18 (, I'd been adding comments and code marking various 
pieces of gdb as "deprecated.

By 5.0 (2000-05) I was explicitly deprecating things.

> > > 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.
>
>
> Chasing after people vs deprecating every code portion you don't want
> to try to fix are not the only two alternatives to solve the problem.

First, from the point of view of GDB's core.  Everything is typically 
fixed.  The problem is with the frindges - architecture / target / 
symtab / ... / specific code - that continues to use or rely on 
mechanisms long after the're no longer needed.

Are you suggesting that I should be required to fix the fringes?

We've debated that in the past and it was agreed (eventually even by 
some of the protractors) that we're better off having the person in a 
position to test the changes make the changes - the rationale is simple 
- we've consistently demonstrated that untested changes don't work.  We 
just end up retaining totally broken but still buildable code.

> And even if those _are_ the only two alternatives, there's still a lot
> of leeway as to the point where you stop chasing and start deprecating.
> And the location of that point is _exactly_ what we disagree about.

I'm lost.

To my knowledge the "point where you stop chasing and start deprecating" 
is _not_ what this debate is about.  Rather it is about what action 
should be taken when deprecating something:

I believe your position is that:
- something is identified as deprecated
- it's recorded somewhere other than the code
- we "fix" all [remining?] uses
- the code is marked up
while mine is:
- something is identified as deprecated
- the code is marked up
- we "fix" all remaining uses

The problem I have with your suggested change, and the reason I 
originally started explicitly deprecating was that I found it doesn't 
work - very early on I was recording things in just the documentation. 
The only effective way I've found of stopping the "breeding" of 
deprecated code is by having it explicitly identified in the code itself 
using markup.

This clarification has had other benefits: it for instance has given us 
a more objective metric against which new contributions and updates can 
be measured - in the past it was very much a hit or miss (reviewer 
dependant) afair.

I know it's also suffered from a few persistant grypes:

- it makes merging hard
During the period 2000 (when CVS went live) to mid 2003 (my role was 
changed) I was responsible for merging the public repository into "the 
cygnus tree".  Given that I was performing weekly merges without problem 
I don't see what the problem is (and I was definitly eating my own dog 
food).

- the bar keeps moving (up)
As I've noted in another post, GDB's code base needs to advance and 
advancing it means continuous change.  One consequence of that change is 
deprecation.  We have to live with it.

Andrew