← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/documenting-changes.txt

  • Committer: Martin Pool
  • Date: 2010-10-13 04:13:48 UTC
  • mto: This revision was merged to the branch mainline in revision 5495.
  • Revision ID: mbp@sourcefrog.net-20101013041348-fflxmtxyusdtvz35
Developer guide to documenting changes

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/documenting-changes.txt
 
1
===================
 
2
Documenting Changes
 
3
===================
 
4
 
 
5
When you change bzr, please update the relevant documentation for the
 
6
change you made:
 
7
 
 
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".
 
12
 
 
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
 
16
  or any help topics.
 
17
 
 
18
Fixing a bug
 
19
  If the bug has any user-visible impact, describe it in the NEWS file
 
20
  in such a way that users can tell whether the problem they're
 
21
  experiencing is the one that was fixed.
 
22
 
 
23
Improving performance
 
24
  Mention this under "improvements" in NEWS, and if it's a notable
 
25
  improvement mention it in "What's New".
 
26
 
 
27
Deprecating an API, or adding a new recommended API
 
28
  Mention this in the "API Changes" of NEWS, if it's likely to affect
 
29
  plugin authors.  Consider whether you should also update the developer
 
30
  documentation.
 
31
 
 
32
Changing the way the test suite works or adding more tests
 
33
  Mention this under "Testing" in NEWS, and update the developer guide
 
34
  to testing.
 
35
 
 
36
Purely internal changes
 
37
  If the change has no user-visible impact and is not interesting to 
 
38
  plugin developers, it doesn't need to be mentioned in NEWS.  If you're 
 
39
  setting a new pattern or adding a new abstraction, update the developer
 
40
  docs.
 
41
 
 
42
NEWS File
 
43
---------
 
44
 
 
45
If you make a user-visible change, please add a note to the NEWS file.
 
46
The description should be written to make sense to someone who's just
 
47
a user of bzr, not a developer: new functions or classes shouldn't be
 
48
mentioned, but new commands, changes in behaviour or fixed nontrivial
 
49
bugs should be listed.  See the existing entries for an idea of what
 
50
should be done.
 
51
 
 
52
Within each release, entries in the news file should have the most
 
53
user-visible changes first.  So the order should be approximately:
 
54
 
 
55
* changes to existing behaviour - the highest priority because the
 
56
  user's existing knowledge is incorrect
 
57
* new features - should be brought to their attention
 
58
* bug fixes - may be of interest if the bug was affecting them, and
 
59
  should include the bug number if any
 
60
* major documentation changes, including fixed documentation bugs
 
61
 
 
62
People who made significant contributions to each change are listed in
 
63
parenthesis.  This can include reporting bugs (particularly with good
 
64
details or reproduction recipes), submitting patches, etc.
 
65
 
 
66
To help with merging, NEWS entries should be sorted lexicographically
 
67
within each section.
 
68
 
 
69
Commands
 
70
--------
 
71
 
 
72
The docstring of a command is used by ``bzr help`` to generate help output
 
73
for the command. The list 'takes_options' attribute on a command is used by
 
74
``bzr help`` to document the options for the command - the command
 
75
docstring does not need to document them. Finally, the '_see_also'
 
76
attribute on a command can be used to reference other related help topics.
 
77
 
 
78
API Documentation
 
79
-----------------
 
80
 
 
81
Functions, methods, classes and modules should have docstrings
 
82
describing how they are used.
 
83
 
 
84
The first line of the docstring should be a self-contained sentence.
 
85
 
 
86
For the special case of Command classes, this acts as the user-visible
 
87
documentation shown by the help command.
 
88
 
 
89
The docstrings should be formatted as reStructuredText_ (like this
 
90
document), suitable for processing using the epydoc_ tool into HTML
 
91
documentation.
 
92
 
 
93
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
94
.. _epydoc: http://epydoc.sourceforge.net/