5
When you change bzr, please update the relevant documentation for the
8
Changing existing behavior
9
If the change will break existing command lines, or break
10
interoperability with other versions of Bazaar, mention this in
11
"External Compatibility Breaks" in NEWS, and also in "What's New".
13
Adding a new feature, function or option
14
Describe this in NEWS, in the user guide, and in the "What's New"
15
document. Consider whether you should also update command help
18
A new hook or extension point
19
These are also described in NEWS, in the hook documentation, and in
20
"What's New." Even though they might be API-only changes, the fact that
21
they exist may interest users enough to write a new plugin that uses
25
If the bug has any user-visible impact, describe it in the NEWS file
26
in such a way that users can tell whether the problem they're
27
experiencing is the one that was fixed.
30
Mention this under "improvements" in NEWS, and if it's a notable
31
improvement mention it in "What's New".
33
Deprecating an API, or adding a new recommended API
34
Mention this in the "API Changes" of NEWS, if it's likely to affect
35
plugin authors. Consider whether you should also update the developer
38
Changing the way the test suite works or adding more tests
39
Mention this under "Testing" in NEWS, and update the developer guide
42
Purely internal changes
43
If the change has no user-visible impact and is not interesting to
44
plugin developers, it doesn't need to be mentioned in NEWS. If you're
45
setting a new pattern or adding a new abstraction, update the developer
51
If you make a user-visible change, please add a note to the NEWS file.
52
The description should be written to make sense to someone who's just
53
a user of bzr, not a developer: new functions or classes shouldn't be
54
mentioned, but new commands, changes in behaviour or fixed nontrivial
55
bugs should be listed. See the existing entries for an idea of what
58
Within each release, entries in the news file should have the most
59
user-visible changes first. So the order should be approximately:
61
* changes to existing behaviour - the highest priority because the
62
user's existing knowledge is incorrect
63
* new features - should be brought to their attention
64
* bug fixes - may be of interest if the bug was affecting them, and
65
should include the bug number if any
66
* major documentation changes, including fixed documentation bugs
68
People who made significant contributions to each change are listed in
69
parenthesis. This can include reporting bugs (particularly with good
70
details or reproduction recipes), submitting patches, etc.
72
To help with merging, NEWS entries should be sorted lexicographically
78
The docstring of a command is used by ``bzr help`` to generate help output
79
for the command. The list 'takes_options' attribute on a command is used by
80
``bzr help`` to document the options for the command - the command
81
docstring does not need to document them. Finally, the '_see_also'
82
attribute on a command can be used to reference other related help topics.
87
Functions, methods, classes and modules should have docstrings
88
describing how they are used.
90
The first line of the docstring should be a self-contained sentence.
92
For the special case of Command classes, this acts as the user-visible
93
documentation shown by the help command.
95
The docstrings should be formatted as reStructuredText_ (like this
96
document), suitable for processing using the epydoc_ tool into HTML
99
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
100
.. _epydoc: http://epydoc.sourceforge.net/
added
removed
doc/developers/documenting-changes.txt
