Bazaar

Merge lp:~mbp/bzr/doc into lp:bzr

  1. doc
  2. Merge into bzr.dev
Proposed by Martin Pool
Status: Merged
Approved by: Vincent Ladeuil
Approved revision: no longer in the source branch.
Merged at revision: 5420
Proposed branch: lp:~mbp/bzr/doc
Merge into: lp:bzr
Diff against target: 107 lines (+53/-4)
3 files modified
bzrlib/builtins.py (+3/-0)
doc/developers/code-style.txt (+32/-0)
doc/developers/ppa.txt (+18/-4)
To merge this branch: bzr merge lp:~mbp/bzr/doc
Reviewer Review Type Date Requested Status
Vincent Ladeuil Needs Fixing
Review via email: mp+35243@code.launchpad.net

Commit message

various developer document improvements

Description of the change

Add a few more developer guidelines.

To post a comment you must log in.
Revision history for this message
Vincent Ladeuil (vila) wrote :

BB:tweak

s/I think//

otherwise, fine.

review: Needs Fixing
Revision history for this message
Martin Pool (mbp) wrote :

sent to pqm by email

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'bzrlib/builtins.py'
2--- bzrlib/builtins.py 2010-08-31 08:57:28 +0000
3+++ bzrlib/builtins.py 2010-09-13 08:23:41 +0000
4@@ -3481,6 +3481,9 @@
5 If you set BZR_TEST_PDB=1 when running selftest, failing tests will drop
6 into a pdb postmortem session.
7
8+ The --coverage=DIRNAME global option produces a report with covered code
9+ indicated.
10+
11 :Examples:
12 Run only tests relating to 'ignore'::
13
14
15=== modified file 'doc/developers/code-style.txt'
16--- doc/developers/code-style.txt 2010-06-02 04:39:08 +0000
17+++ doc/developers/code-style.txt 2010-09-13 08:23:41 +0000
18@@ -101,6 +101,38 @@
19 if getattr(thing, 'name', None) is None
20
21
22+kwargs
23+======
24+
25+``**kwargs`` in the prototype of a function should be used sparingly.
26+It can be good on higher-order functions that decorate other functions,
27+such as ``addCleanup`` or ``assertRaises``, or on functions that take only
28+(or almost only) kwargs, where any kwargs can be passed.
29+
30+Otherwise, be careful: if the parameters to a function are a bit complex
31+and might vary over time (e.g. the ``commit`` API) then we prefer to pass an
32+object rather than a bag of positional and/or keyword args. If you have
33+an arbitrary set of keys and values that are different with each use (e.g.
34+string interpolation inputs) then again that should not be mixed in with
35+the regular positional/keyword args, it seems like a different category of
36+thing.
37+
38+
39+Imitating standard objects
40+==========================
41+
42+Don't provide methods that imitate built-in classes (eg ``__in__``,
43+``__call__``, ``__int__``, ``__getitem__``) unless the class you're
44+implementing really does act like the builtin class, in semantics and
45+performance.
46+
47+For example, old code lets you say ``file_id in inv`` but we no longer
48+consider this good style. Instead, say more explicitly
49+``inv.has_id(file_id)``.
50+
51+``__repr__``, ``__cmp__``, ``__str__`` are usually fine.
52+
53+
54 Module Imports
55 ==============
56
57
58=== modified file 'doc/developers/ppa.txt'
59--- doc/developers/ppa.txt 2010-08-27 00:33:07 +0000
60+++ doc/developers/ppa.txt 2010-09-13 08:23:41 +0000
61@@ -15,8 +15,9 @@
62
63 As of June 2010, there are three PPAs:
64
65-<https://launchpad.net/~bzr/+archive>
66+<https://launchpad.net/~bzr/+archive/ppa>
67 Final released versions and updates.
68+ Most users who want updates to bzr should add this.
69
70 <https://launchpad.net/~bzr/+archive/proposed>
71 Proposed uploads to move into ~bzr, awaiting testing.
72@@ -130,12 +131,12 @@
73 * Now merge across that change into each supported branch with a
74 simple ``bzr merge``.
75
76-Locally testing builds
77-~~~~~~~~~~~~~~~~~~~~~~
78+Locally testing using pbuilder
79+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
81 It may be useful to locally test builds inside pbuilder. You may want to
82 use the script from <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=255165>
83-to wrap it.
84+to wrap it, and to give it sensible defaults for your local machine.
85
86 Update all packages in proposed before copping the main ppa
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88@@ -328,7 +329,20 @@
89 apt-cache madison bzr
90
91
92+Testing the contents of the PPA
93+-------------------------------
94+
95+A somewhat crude but useful way to test the contents of the PPA is to
96+install the relevant packages into an schroot::
97+
98+ schroot -c hardy-test -u root -- \
99+ apt-get install -o 'APT::Install-Suggests="true"' \
100+ -o 'APT::Install-Recommends="true"' \
101+ bzr
102+
103+This should make sure everything can be installed; it won't guarantee that
104
105+
106 Packaging dependencies
107 ----------------------
108