This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: A new strategy for internals documentation
- From: Stan Shebs <stanshebs at earthlink dot net>
- To: gdb at sourceware dot org
- Date: Fri, 09 Aug 2013 15:31:32 -0700
- Subject: Re: A new strategy for internals documentation
- References: <5201781A dot 3000607 at earthlink dot net> <83k3jyunt8 dot fsf at gnu dot org> <52031434 dot 2080005 at codesourcery dot com> <83k3jwt7in dot fsf at gnu dot org> <201308090129 dot r791Tw6a016114 at new dot toad dot com>
On 8/8/13 6:29 PM, John Gilmore wrote:
> The real issue is not about where the information is stored. The real
> issue is that people are evolving the code base without evolving the
> matching documentation. This is accepted to be a sin with regard to
> the "Debugging with GDB" manual, which IS required to be complete,
> definitive, tutorial, and readable. Could I gently suggest that
> contributors who make patches that evolve e.g. the symbol table handling,
> but who don't document their improvements in Gdbint, be gently reminded
> to improve and resubmit their patch by including a patch to gdbint as well?
In theory that's always been the case, but once the manual fell out of
sync, it was easy to reply with "my change refers to material not in the
manual" or "I don't have the time nor understanding to get the internals
manual back up to date". We also have never had consensus among the
maintainers whether this was something to enforce, and it
only take one maintainer approving patches (or committing their own)
that change the internals, and the manual immediately stop reflecting
reality.
> I started the GDB Internals manual. Why? Because we had no place to
> record textual explanations about why and how GDB is internally
> structured.
The ironic thing is that no one working on a new free software project
today would react to that situation by saying "we need an internals
manual". The project would add a wiki page, send an email, or maybe a
blog posting, or a long comment block in the source code. If there were
a half-dozen files to edit in sync, these days there is more likely to
be intense pressure to refactor that code and bring it back down to one
place to edit, which would then be the place for the documentation about it.
While your detailed points are logically valid, we have twenty years of
empirical experience that says reality is not conforming to what we
originally imagined. So I've suggested a Plan B where we try a couple
alternatives that are known to have a good track record in other
projects; they do not entail massive commitments or even very much
change initially. If neither work out, then we shrug, drop them, and
think of a Plan C to try instead.
Stan
stan@codesourcery.com