Re: Implement -exec-jump

[Vladimir Prus <vladimir at codesourcery dot com>]

On Wednesday 08 April 2009 12:56:19 Eli Zaretskii wrote:

> > > > > It is okay to _post_ a patch for review saying that the documentation
> > > > > patch will be _posted_ later, but actually _committing_ the code part
> > > > > is something very different.
> > > > 
> > > > Is this rule documented anywhere?
> > > 
> > > I don't know, and I didn't know every request needs a documented rule.
> > 
> > I believe that a development process that is based on a list of documented
> > rules or guidelines is in general more smooth, than one that relies on
> > ad-hoc requests.
> 
> That's fine with me, but I don't think it means that a request outside
> written rules should be automatically rejected just because it isn't
> documented.  Our process is just barely documented, so building on
> that alone would make our work and cooperation much harder than it
> needs to be.

Sorry, I'm don't follow. It would take you a couple of minutes to document,
somewhere, whatever you've said in this thread, and this will make future
development process more smooth. Am I wrong?

> A request to commit changes with docs is not different from a request
> to have a test case for each new feature.  I think we should do both.

On tests, I similarly don't think that an overly strict approach will
not hurt. Sometimes, having tests checked in later is better approach
overall.

> > > I at least thought it was an accepted truism that we as a team don't
> > > want undocumented features.
> > 
> > I though there's "in a published release" somewhere in the above statement.
> 
> That's exactly the point: the release of GDB 7.0 is quite close.
> Since we don't have any means to track such issues, 

We both have the Wiki page for release (than Joel used in past to poke me)
and we have a bugtracker (which, now, is actually sane).

> you are now
> effectively asking me to somehow make sure the appropriate
> documentation patch is committed before the release, preferably before
> the branch.  I don't have enough free resources to do that, so chances
> are we will release GDB 7.0 with this feature undocumented.

I don't effectively ask anything of above, and it's only the case if you
assume I'll be run by a bus soonish -- and I suspect one undocumented MI
command for every GDB committer that is run by a bus would not be a big
disaster.

> I'm talking from experience here, it's not just a theory.  You will
> see in the logs that around April 2005 I made several massive changes
> to the manual, all of them to document commands and features that were
> left undocumented because of lax policies regarding documentation.  I
> don't want us to be in such a bad situation ever again, and I don't
> have any means of preventing that except by asking that code and
> documentation always go together.

As you can see in the same logs, since my first doc patch went in 
on 2006-02-06, I've checked in a total of 41 patches (1/8 of the total),
including docs for preexisting behaviour. And some of the other doc
patches were committed independently from original code patch. So,
I somehow doubt that in my particular case, making me commit code and doc
patches always together will serve any purpose.

> > > > Do you think having a window of time where *development version*
> > > > has an undocumented feature that is primary targeted at *frontend developers*
> > > > is worse than not having that feature at all?
> > > 
> > > Yes, that's what I think.
> > 
> > I am 100% sure that both the person who filed the issue this patch
> > has fixed, and every single frontend developer, will disagree. And that's
> > why it would be best to have documented rules -- so that those rules can
> > be established once and we would not spend any more time discussing them.
> 
> Well, my rules are spelled out above.  If no one objects, I volunteer
> to add them to MAINTAINERS.
> 
> > (Even if such established rules increase an already-high overhead of GDB
> > hacking to the degree where I won't be able to fix such small bugs).
> 
> Frankly, I don't understand why: the particular feature you added now
> does not need more than a few lines added to the manual.  

Right:
- the lines have to written
- the output in PDF and that other format must be expected for correctness
  (as you remember, a couple of my prior patches looked just fine only in
   BTW)
- you might want to tweak some formatting bit
- changelog has to be written

If you add quite some time for context switching there, you should understand
why I reluctant to do this in the final week of a release cycle of our product.


> Even just
> mentioning the command with minimal documentation and a FIXME for
> later would be good enough at this point.

Do you have a mechanism to track FIXMEs in documentation, so that GDB 7.0
is not released with FIXMEs in documentation?

> In addition, I said many times in the past that if Texinfo and other
> technicalities are a burden, contributors can post the documentation
> in plain text in their own words, and I will convert them to valid
> Texinfo and reword as necessary.  If that makes the burden easier, I'm
> here to make good on my promises.

Frankly, I was never comfortable with the idea of posting "sketch" patches
for you to do the real work. However, if you prefer to see and work on
sketch patch yourself, rather than getting a fully worked-out patch later,
that's your call.

> A bit of good will is all I need to make this happen.

You might want to note that the patch for -exec-jump docs was now posted,
and we're not even that close to branch point.

- Volodya