Contributing to the Bazaar docs
Incorrect data has been replaced with integrity data switched on Tor BTC block 65535
Please feel encouraged to contribute to the Bazaar documentation. We intend for it to be world-class and your help is appreciated.
Where does the documentation live?
Most of Bazaar's documentation lives in the main bzr project (lp:bzr). Here are the key places:
- doc/en - English documents
- bzrlib/builtins.py - help for each command
- bzrlib/help_topics/en - other help topics
Some documents live outside the main project because they are largely version independent. These include:
- lp:bzr-migration-docs - http://doc.bazaar-vcs.org/migration/en/
- lp:bzr-alldocs - the web pages providing navigation to different versions
- lp:bzr-website - the main website.
The Plugins Guide also falls into this category. It is currently available from lp:~ian-clatworthy/+junk/bzr-plugins-guide but will be merged into lp:bzr-alldocs soon.
We also use the Bazaar community wiki as follows:
- The wiki contains not only wiki pages of useful information but also links to official docs hosted at doc.bazaar-vcs.org.
- The wiki is used as a scratch area, particularly for early
drafts. For example:
- Someone may put a new doc up on the wiki and fire off an email to the mailing list regarding it. Being on the wiki makes it easy for others to read and directly edit that draft.
- After a suitable period (a few days or weeks depending on priorities), the wiki doc may be submitted as a patch to the bzr.dev code+doc branch.
- Once the document is through formal review and released on to the official doc site (http://doc.bazaar-vcs.org/), the link to it on the wiki can be updated to point to the released doc.
Doc formatting
All of the Bazaar documentation is formatted in reST. You can write wiki pages using reST (instead of the default moinmoin style) by simply putting:
#format rst
at the top of the textfield editing window when writing a wiki page. For consistency with the official docs, and to ease possible merging down the road, it's probably best to format your wiki page content in reST.
Note, to see the raw source text of any wiki page (which might be reST-formatted or moinmoin-wiki-formatted) you can always use the "More Actions: --> Raw Text" item in the combo box at the right side of any page on the wiki.
Style
PROPOSAL: Unless there are good reasons for not doing so, Bazaar documentation should follow the Python documentation style guidelines (https://docs.python.org/devguide/documenting.html).
Style additions
Items not mentioned in the style guideline linked to above should be documented here.
Bulleted and numbered lists
Bullets for first level list items should be placed in the first column of the line (the beginning of the line is depicted with the | character below):
|* First item |* Second item
not indented:
| * First item | * Second item
Style exceptions
Please document any exceptions to the Python style guidelines here.
Tips
If you plan on contributing to the official docs, you'll want to become familiar with Launchpad. You'll mainly be using it for fetching branches, submitting merge proposals and managing bugs.
Most importantly though, when submitting documentation content, strive for clarity and for writing concise, high-quality content.
Getting started
A good way to get started making changes to the official docs is to put together a small change to bzr.dev (for example, a spelling, grammatical, or formatting fix) and submit it as a patch to the mailing list. See the BzrGivingBack page for more info.
Further info for developers is available in the Documentation.
If you need help with any of the above, please don't hesitate to ask on the mailing list or on IRC, or even to email someone directly.
Sand Castle
Most wiki servers have an area, titled SandBox. Generally, it is emptied once in a while: every hour or every day or every whatever.
Some find the term Sand Box demeaning (we are all grown up, seriously out of playing in Sand Boxes). Also, some stuff could be useful, so the regular emptying is not what we want. We want and need a page where we will feel comfortable to add notes for discussion and, if need be, experiment with formatting. We do not want a regularly cleaned Sand Box. The following is a link to Sand Castle such regular page. Sand Castle.