1 = Bug XXXXXX =
   2 
   3 This section's purpose is to explain, in human readable terms <wink> what the
   4 bug is all about.  It might seem redundant to do so when the bug number is
   5 included in the header, but often bug threads are not very easy to follow, or
   6 the bug is not explained very well by the OP.  Sometimes, bug threads bring up
   7 tangential issues, or describe several possible causes, etc.  This section of
   8 the cover letter boils it all down to the essentials.
   9 
  10 For example:
  11 
  12 Bug XXXXXX describes a problem where a Launchpad user tries to frobnicate his
  13 foobar but Launchpad won't let him do so, even if he is a member of the proper
  14 team.  Bug YYYYYY appears to be related except that it also affects team
  15 admins.
  16 
  17 
  18 == Proposed fix ==
  19 
  20 This section's purpose is to describe your analysis of the problem, along with
  21 your proposed fix.  Why is the user having the problem described above?
  22 What's wrong with the code and how are you going to change it to resolve the
  23 user's problem?
  24 
  25 For example:
  26 
  27 The problem is caused by IPerson.frobnicate() not checking team membership.
  28 The proposed fix then is to add a check of team participation before we
  29 attempt to frobnicate().
  30 
  31 
  32 == Pre-implementation notes ==
  33 
  34 You've discussed the bug and your proposed fix with a fellow developer.  This
  35 section captures the details of that conversation, including any notes or
  36 other things your pre-implementation call uncovered.
  37 
  38 For example:
  39 
  40 I discussed this bug with Brad who pointed out that we should be checking team
  41 participation and not team membership.  Brad also cautioned me to watch out
  42 for the +editemails page, where the same problem can occur in baznification.
  43 Indeed upon further investigation, the same change should be made in
  44 IPerson.baznify() so we agreed that I should refactor the check into a
  45 non-public helper method to be used in both places.
  46 
  47 
  48 == Implementation details ==
  49 
  50 Inevitably, implementation raises other issues.  You're just not going to
  51 think of everything during planning and pre-implementation call, and you'll
  52 only discover these things once you start coding.  You may also notice things
  53 along the way that can be cleaned up or improved in a drive-by.  This section
  54 describes all the things you learned or did during the implementation phase of
  55 your branch.  This section can also include a file-by-file summary of your
  56 changes.
  57 
  58 For example:
  59 
  60 While refactoring the team participation check, I realized that there were
  61 several other places in the code that could use the same check, so I also
  62 refactored them.  I realized that it made much more sense to turn the
  63 AssertionError into a more specific exception, so I added
  64 BadBaznificationError and changed all the call sites.  While I was at it, I
  65 cleaned up some of the imports to use more specific imports and cleaned up
  66 some whitespace issues in the interface.
  67 
  68 interface/person.py:
  69  * Added BadBaznificationError
  70 
  71 database/person.py:
  72  * Refactored team membership check into a _frobCheck() method
  73  * Cleaned up some whitespace
  74 
  75 doc/person.txt
  76  * Added a test for the new checks and exceptions
  77 
  78 doc/frob-pages.txt
  79  * Added a new doctest to verify that the view attributes work as expected
  80  * Added new tests for posting to the view
  81 
  82 pagetest/foaf/frob.txt
  83  * Added a page test for navigation to the new +frob page.
  84 
  85 
  86 == Tests ==
  87 
  88 This section describes how to test your code.  It often contains just a
  89 command line explaining how to run your modified tests, but it may also
  90 contain other instructions for testing your work.  If for example, some of
  91 your changes may have caused regressions that existing tests check for, you
  92 should add them here.
  93 
  94 For example:
  95 
  96 ./test.py -vv -t person.txt -t frob
  97 
  98 The changes could have introduced a regression in baznification, but the
  99 following tests ensure that this did not happen.
 100 
 101 ./test.py -vv -t baznify
 102 
 103 
 104 == Demo and Q/A ==
 105 
 106 Demoing your changes and doing Q/A on them are closely related.  This section
 107 describes your Q/A plan, which is often the same steps a reviewer could use to
 108 demo your change.  It's important that you have a Q/A plan in mind before your
 109 begin work on your branch.
 110 
 111 For example:
 112 
 113 To demo and Q/A this change, do the following:
 114 
 115  * Log on as Sample Person (test@canonical.com:test)
 116  * Visit http://launchpad.dev/firefox
 117  * Click the Frob button
 118  * Observe that the frobnication succeeds
 119 
 120 
 121 == lint ==
 122 
 123 Here's the output of your 'make lint' command.  It if is not clean, explain
 124 why the reviewer should ignore the lint warnings.
 125 
 126 
 127 == diff ==
 128 
 129 Here is your branch's diff.  It's better to include this in the cover letter
 130 rather than a separate post, because it makes it easier for a reviewer to
 131 comment on the entire thing, which will be in a single email, rather than
 132 having to comment on multiple email messages.  Enclose your diff in
 133 triple-braces.
 134 
 135 {{{
 136 diff-output
 137 }}}