Rev 5420: (mbp) various developer document improvements (Martin Pool) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 5420 [merge]
revision-id: pqm at pqm.ubuntu.com-20100913095203-w7z5eyx3fzdb24wi
parent: pqm at pqm.ubuntu.com-20100913075939-nh4c1k7rkuxle7zk
parent: mbp at sourcefrog.net-20100913082057-ssrdeu6iya6uq42h
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2010-09-13 10:52:03 +0100
message:
  (mbp) various developer document improvements (Martin Pool)
modified:
  bzrlib/builtins.py             builtins.py-20050830033751-fc01482b9ca23183
  doc/developers/code-style.txt  codestyle.txt-20100515105711-133ealf7ereiq2eq-1
  doc/developers/ppa.txt         ppa.txt-20080722055539-606u7t2z32t3ae4w-1
=== modified file 'bzrlib/builtins.py'
--- a/bzrlib/builtins.py	2010-08-31 08:57:28 +0000
+++ b/bzrlib/builtins.py	2010-09-13 05:01:57 +0000
@@ -3481,6 +3481,9 @@
     If you set BZR_TEST_PDB=1 when running selftest, failing tests will drop
     into a pdb postmortem session.
 
+    The --coverage=DIRNAME global option produces a report with covered code
+    indicated.
+
     :Examples:
         Run only tests relating to 'ignore'::
 

=== modified file 'doc/developers/code-style.txt'
--- a/doc/developers/code-style.txt	2010-06-02 04:39:08 +0000
+++ b/doc/developers/code-style.txt	2010-09-13 08:20:57 +0000
@@ -101,6 +101,38 @@
   if getattr(thing, 'name', None) is None
 
 
+kwargs
+======
+
+``**kwargs`` in the prototype of a function should be used sparingly.
+It can be good on higher-order functions that decorate other functions,
+such as ``addCleanup`` or ``assertRaises``, or on functions that take only
+(or almost only) kwargs, where any kwargs can be passed.  
+
+Otherwise, be careful: if the parameters to a function are a bit complex
+and might vary over time (e.g.  the ``commit`` API) then we prefer to pass an
+object rather than a bag of positional and/or keyword args.  If you have
+an arbitrary set of keys and values that are different with each use (e.g.
+string interpolation inputs) then again that should not be mixed in with
+the regular positional/keyword args, it seems like a different category of
+thing.
+
+
+Imitating standard objects
+==========================
+
+Don't provide methods that imitate built-in classes (eg ``__in__``,
+``__call__``, ``__int__``, ``__getitem__``) unless the class you're
+implementing really does act like the builtin class, in semantics and
+performance.
+
+For example, old code lets you say ``file_id in inv`` but we no longer
+consider this good style.  Instead, say more explicitly
+``inv.has_id(file_id)``.
+
+``__repr__``, ``__cmp__``, ``__str__`` are usually fine.
+
+
 Module Imports
 ==============
 

=== modified file 'doc/developers/ppa.txt'
--- a/doc/developers/ppa.txt	2010-08-27 00:33:07 +0000
+++ b/doc/developers/ppa.txt	2010-09-13 02:03:04 +0000
@@ -15,8 +15,9 @@
 
 As of June 2010, there are three PPAs:
 
-<https://launchpad.net/~bzr/+archive>
+<https://launchpad.net/~bzr/+archive/ppa>
     Final released versions and updates.
+    Most users who want updates to bzr should add this.
 
 <https://launchpad.net/~bzr/+archive/proposed>
     Proposed uploads to move into ~bzr, awaiting testing.
@@ -130,12 +131,12 @@
 * Now merge across that change into each supported branch with a 
   simple ``bzr merge``.
   
-Locally testing builds
-~~~~~~~~~~~~~~~~~~~~~~
+Locally testing using pbuilder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It may be useful to locally test builds inside pbuilder.  You may want to 
 use the script from <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=255165> 
-to wrap it.
+to wrap it, and to give it sensible defaults for your local machine.
 
 Update all packages in proposed before copping the main ppa
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -328,7 +329,20 @@
   apt-cache madison bzr
   
   
+Testing the contents of the PPA
+-------------------------------
+
+A somewhat crude but useful way to test the contents of the PPA is to
+install the relevant packages into an schroot::
+
+ schroot -c hardy-test -u root -- \
+   apt-get install -o 'APT::Install-Suggests="true"' \
+   -o 'APT::Install-Recommends="true"' \
+   bzr
+
+This should make sure everything can be installed; it won't guarantee that 
   
+
 Packaging dependencies
 ----------------------