Bazaar Developer Guide (Proposed)

Martin Pool mbp at sourcefrog.net
Thu Apr 12 03:46:19 BST 2007


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
docs.bazaar-vcs.org

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"

-- 
Martin



More information about the bazaar mailing list