Summary

This section's purpose is to explain, in human readable terms <wink> what the bug or blueprint is all about. It might seem redundant to do so when the bug number is usually included here, but often bug threads are not very easy to follow, or the bug is not explained very well by the OP. Sometimes, bug threads bring up tangential issues, or describe several possible causes, etc. This section of the cover letter boils it all down to the essentials.

For example:

Bug XXXXXX describes a problem where a Launchpad user tries to frobnicate his foobar but Launchpad won't let him do so, even if he is a member of the proper team. Bug YYYYYY appears to be related except that it also affects team admins.

Proposed fix

This section's purpose is to describe your analysis of the problem, along with your proposed fix. Why is the user having the problem described above? What's wrong with the code and how are you going to change it to resolve the user's problem?

For example:

The problem is caused by IPerson.frobnicate() not checking team membership. The proposed fix then is to add a check of team participation before we attempt to frobnicate().

Pre-implementation notes

You've discussed the bug and your proposed fix with a fellow developer. This section captures the details of that conversation, including any notes or other things your pre-implementation call uncovered.

For example:

I discussed this bug with Brad who pointed out that we should be checking team participation and not team membership. Brad also cautioned me to watch out for the +editemails page, where the same problem can occur in baznification. Indeed upon further investigation, the same change should be made in IPerson.baznify() so we agreed that I should refactor the check into a non-public helper method to be used in both places.

Implementation details

Inevitably, implementation raises other issues. You're just not going to think of everything during planning and pre-implementation call, and you'll only discover these things once you start coding. You may also notice things along the way that can be cleaned up or improved in a drive-by. This section describes all the things you learned or did during the implementation phase of your branch. This section can also include a file-by-file summary of your changes.

For example:

While refactoring the team participation check, I realized that there were several other places in the code that could use the same check, so I also refactored them. I realized that it made much more sense to turn the AssertionError into a more specific exception, so I added BadBaznificationError and changed all the call sites. While I was at it, I cleaned up some of the imports to use more specific imports and cleaned up some whitespace issues in the interface.

interface/person.py:

database/person.py:

doc/person.txt

doc/frob-pages.txt

pagetest/foaf/frob.txt

Tests

This section describes how to test your code. It often contains just a command line explaining how to run your modified tests, but it may also contain other instructions for testing your work. If for example, some of your changes may have caused regressions that existing tests check for, you should add them here.

For example:

bin/test -vv -t person.txt -t frob

The changes could have introduced a regression in baznification, but the following tests ensure that this did not happen.

bin/test -vv -t baznify

Demo and Q/A

Demoing your changes and doing Q/A on them are closely related. This section describes your Q/A plan, which is often the same steps a reviewer could use to demo your change. It's important that you have a Q/A plan in mind before your begin work on your branch.

For example:

To demo and Q/A this change, do the following:

DetailedCoverLetterTemplate (last edited 2021-08-24 10:10:19 by cjwatson)