Bazaar Developer Guide (Proposed)
mbp at sourcefrog.net
Thu Apr 26 06:35:25 BST 2007
To make sure the good work in this thread doesn't get forgotten, Ian
could you sometime turn your outline into a patch to HACKING and put
it up for review?
On 4/12/07, Martin Pool <mbp at sourcefrog.net> wrote:
> On where to store this: we had some discussion on irc (#bzr on
> freenode) and the people who were there (abentley, mbp, robertc, ianc,
> spiv) agreed that we would:
> * put the developer guide in the source tree (in HACKING), rather
> than moving it to the wiki
> * keep it in ReST format
> * automatically put the html form onto docs.bazaar-vcs.org
> * identify wiki pages which ought to be combined with this, move
> their text across, and replace them with a pointer to
> If we keep it in the source tree it should be easier for reviewers to
> think "should this change require an update to the documentation?", as
> we do for tests.
> We need to be responsive to people who want to add to the docs just by
> posting new text in a bug or list post, rather than as a bundle.
> Now as far as how it's cut up: at the moment the developer documentation is in
> - HACKING
> - some wiki pages
> - docstrings
> - some text files under bzrlib/doc/api, giving brief overviews of
> Branch and Transport
> I think we could consolidate this to
> - one "developer guide" in HACKING, giving you an overview of the
> internals and talking about the big concepts
> - pydocs with details on classes or modules
> docstrings are a good place to put details but there's no structure as
> to where you should start reading; I think a guide type document does
> that best.
> The ToC looks good, I think you could even merge those headings into
> the current document just as placeholders. Some specific comments:
> There could be a top level heading about "understanding the
> development process". I see you mention it in the introduction, which
> is good, but there are also some topics about reviews and bundle buggy
> in "misc"
> Also we could add "how to write a plugin"
More information about the bazaar