<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Documenting Changes — Bazaar 2.7.0 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="shortcut icon" href="_static/bzr.ico"/>
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Configuring Bazaar" href="configuration.html" />
<link rel="prev" title="Bazaar Code Style Guide" href="code-style.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="configuration.html" title="Configuring Bazaar"
accesskey="N">next</a></li>
<li class="right" >
<a href="code-style.html" title="Bazaar Code Style Guide"
accesskey="P">previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="documenting-changes">
<h1>Documenting Changes<a class="headerlink" href="#documenting-changes" title="Permalink to this headline">¶</a></h1>
<p>When you change bzr, please update the relevant documentation for the
change you made:</p>
<dl class="docutils">
<dt>Changing existing behavior</dt>
<dd>If the change will break existing command lines, or break
interoperability with other versions of Bazaar, mention this in
“External Compatibility Breaks” in NEWS, and also in “What’s New”.</dd>
<dt>Adding a new feature, function or option</dt>
<dd>Describe this in NEWS, in the user guide, and in the “What’s New”
document. Consider whether you should also update command help
or any help topics.</dd>
<dt>A new hook or extension point</dt>
<dd>These are also described in NEWS, in the hook documentation, and in
“What’s New.” Even though they might be API-only changes, the fact that
they exist may interest users enough to write a new plugin that uses
them.</dd>
<dt>Fixing a bug</dt>
<dd>If the bug has any user-visible impact, describe it in the NEWS file
in such a way that users can tell whether the problem they’re
experiencing is the one that was fixed.</dd>
<dt>Improving performance</dt>
<dd>Mention this under “improvements” in NEWS, and if it’s a notable
improvement mention it in “What’s New”.</dd>
<dt>Deprecating an API, or adding a new recommended API</dt>
<dd>Mention this in the “API Changes” of NEWS, if it’s likely to affect
plugin authors. Consider whether you should also update the developer
documentation.</dd>
<dt>Changing the way the test suite works or adding more tests</dt>
<dd>Mention this under “Testing” in NEWS, and update the developer guide
to testing.</dd>
<dt>Purely internal changes</dt>
<dd>If the change has no user-visible impact and is not interesting to
plugin developers, it doesn’t need to be mentioned in NEWS. If you’re
setting a new pattern or adding a new abstraction, update the developer
docs.</dd>
</dl>
<div class="section" id="news-file">
<h2>NEWS File<a class="headerlink" href="#news-file" title="Permalink to this headline">¶</a></h2>
<p>If you make a user-visible change, please add a note to the NEWS file.
The description should be written to make sense to someone who’s just
a user of bzr, not a developer: new functions or classes shouldn’t be
mentioned, but new commands, changes in behaviour or fixed nontrivial
bugs should be listed. See the existing entries for an idea of what
should be done.</p>
<p>Within each release, entries in the news file should have the most
user-visible changes first. So the order should be approximately:</p>
<ul class="simple">
<li>changes to existing behaviour - the highest priority because the
user’s existing knowledge is incorrect</li>
<li>new features - should be brought to their attention</li>
<li>bug fixes - may be of interest if the bug was affecting them, and
should include the bug number if any</li>
<li>major documentation changes, including fixed documentation bugs</li>
</ul>
<p>People who made significant contributions to each change are listed in
parenthesis. This can include reporting bugs (particularly with good
details or reproduction recipes), submitting patches, etc.</p>
<p>To help with merging, NEWS entries should be sorted lexicographically
within each section.</p>
</div>
<div class="section" id="commands">
<h2>Commands<a class="headerlink" href="#commands" title="Permalink to this headline">¶</a></h2>
<p>The docstring of a command is used by <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">help</span></code> to generate help output
for the command. The list ‘takes_options’ attribute on a command is used by
<code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">help</span></code> to document the options for the command - the command
docstring does not need to document them. Finally, the ‘_see_also’
attribute on a command can be used to reference other related help topics.</p>
</div>
<div class="section" id="api-documentation">
<h2>API Documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2>
<p>Functions, methods, classes and modules should have docstrings
describing how they are used.</p>
<p>The first line of the docstring should be a self-contained sentence.</p>
<p>For the special case of Command classes, this acts as the user-visible
documentation shown by the help command.</p>
<p>The docstrings should be formatted as <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> (like this
document), suitable for processing using the <a class="reference external" href="http://epydoc.sourceforge.net/">epydoc</a> tool into HTML
documentation.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Documenting Changes</a><ul>
<li><a class="reference internal" href="#news-file">NEWS File</a></li>
<li><a class="reference internal" href="#commands">Commands</a></li>
<li><a class="reference internal" href="#api-documentation">API Documentation</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="code-style.html"
title="previous chapter">Bazaar Code Style Guide</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="configuration.html"
title="next chapter">Configuring Bazaar</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/documenting-changes.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="configuration.html" title="Configuring Bazaar"
>next</a></li>
<li class="right" >
<a href="code-style.html" title="Bazaar Code Style Guide"
>previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
</div>
</body>
</html>
