Rev 5495: (mbp) document standards for updating news, whatsnew, etc (Martin Pool) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Thu Oct 14 23:53:44 BST 2010
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 5495 [merge]
revision-id: pqm at pqm.ubuntu.com-20101014225343-tsb5hohsfod0a97m
parent: pqm at pqm.ubuntu.com-20101014170046-5knwnfe0nelk2tp3
parent: mbp at sourcefrog.net-20101014212308-avfax5qlqwo1rrb1
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2010-10-14 23:53:43 +0100
message:
(mbp) document standards for updating news, whatsnew, etc (Martin Pool)
added:
doc/developers/documenting-changes.txt documentingchanges.t-20101013040916-yk0dmle751kjoprm-1
modified:
doc/developers/HACKING.txt HACKING-20050805200004-2a5dc975d870f78c
doc/developers/index-plain.txt indexplain.txt-20090909123806-96yfsgrqwra8cwq7-1
doc/developers/index.txt index.txt-20070508041241-qznziunkg0nffhiw-1
=== modified file 'doc/developers/HACKING.txt'
--- a/doc/developers/HACKING.txt 2010-09-03 09:14:12 +0000
+++ b/doc/developers/HACKING.txt 2010-10-13 04:13:48 +0000
@@ -359,70 +359,6 @@
can't fix.
-Documenting Changes
-===================
-
-When you change bzrlib, please update the relevant documentation for the
-change you made: Changes to commands should update their help, and
-possibly end user tutorials; changes to the core library should be
-reflected in API documentation.
-
-NEWS File
----------
-
-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.
-
-Within each release, entries in the news file should have the most
-user-visible changes first. So the order should be approximately:
-
- * changes to existing behaviour - the highest priority because the
- user's existing knowledge is incorrect
- * new features - should be brought to their attention
- * bug fixes - may be of interest if the bug was affecting them, and
- should include the bug number if any
- * major documentation changes, including fixed documentation bugs
- * changes to internal interfaces
-
-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.
-
-To help with merging, NEWS entries should be sorted lexicographically
-within each section.
-
-Commands
---------
-
-The docstring of a command is used by ``bzr help`` to generate help output
-for the command. The list 'takes_options' attribute on a command is used by
-``bzr help`` 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.
-
-API Documentation
------------------
-
-Functions, methods, classes and modules should have docstrings
-describing how they are used.
-
-The first line of the docstring should be a self-contained sentence.
-
-For the special case of Command classes, this acts as the user-visible
-documentation shown by the help command.
-
-The docstrings should be formatted as reStructuredText_ (like this
-document), suitable for processing using the epydoc_ tool into HTML
-documentation.
-
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _epydoc: http://epydoc.sourceforge.net/
-
-
General Guidelines
==================
=== added file 'doc/developers/documenting-changes.txt'
--- a/doc/developers/documenting-changes.txt 1970-01-01 00:00:00 +0000
+++ b/doc/developers/documenting-changes.txt 2010-10-14 21:23:08 +0000
@@ -0,0 +1,100 @@
+===================
+Documenting Changes
+===================
+
+When you change bzr, please update the relevant documentation for the
+change you made:
+
+Changing existing behavior
+ 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".
+
+Adding a new feature, function or option
+ 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.
+
+A new hook or extension point
+ 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.
+
+Fixing a bug
+ 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.
+
+Improving performance
+ Mention this under "improvements" in NEWS, and if it's a notable
+ improvement mention it in "What's New".
+
+Deprecating an API, or adding a new recommended API
+ 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.
+
+Changing the way the test suite works or adding more tests
+ Mention this under "Testing" in NEWS, and update the developer guide
+ to testing.
+
+Purely internal changes
+ 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.
+
+NEWS File
+---------
+
+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.
+
+Within each release, entries in the news file should have the most
+user-visible changes first. So the order should be approximately:
+
+* changes to existing behaviour - the highest priority because the
+ user's existing knowledge is incorrect
+* new features - should be brought to their attention
+* bug fixes - may be of interest if the bug was affecting them, and
+ should include the bug number if any
+* major documentation changes, including fixed documentation bugs
+
+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.
+
+To help with merging, NEWS entries should be sorted lexicographically
+within each section.
+
+Commands
+--------
+
+The docstring of a command is used by ``bzr help`` to generate help output
+for the command. The list 'takes_options' attribute on a command is used by
+``bzr help`` 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.
+
+API Documentation
+-----------------
+
+Functions, methods, classes and modules should have docstrings
+describing how they are used.
+
+The first line of the docstring should be a self-contained sentence.
+
+For the special case of Command classes, this acts as the user-visible
+documentation shown by the help command.
+
+The docstrings should be formatted as reStructuredText_ (like this
+document), suitable for processing using the epydoc_ tool into HTML
+documentation.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _epydoc: http://epydoc.sourceforge.net/
=== modified file 'doc/developers/index-plain.txt'
--- a/doc/developers/index-plain.txt 2010-08-17 06:45:33 +0000
+++ b/doc/developers/index-plain.txt 2010-10-13 04:13:48 +0000
@@ -31,6 +31,8 @@
* `Writing plugins <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_
|--| specific advice on writing Bazaar plugins. (web link)
+* `Documenting changes <documenting-changes.html>`_.
+
Process
=======
=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt 2010-09-03 09:14:12 +0000
+++ b/doc/developers/index.txt 2010-10-13 04:13:48 +0000
@@ -25,6 +25,7 @@
testing
code-review
code-style
+ documenting-changes
* `Contributing to Bazaar Documentation <http://wiki.bazaar.canonical.com/ContributingToTheDocs>`_ (wiki)
More information about the bazaar-commits
mailing list