Bazaar Developer Guide (Proposed)

[Martin Pool]

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


-- 
Martin