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.
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.
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?
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().
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.
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.
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.
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.
- Refactored team membership check into a _frobCheck() method
- Cleaned up some whitespace
- Added a test for the new checks and exceptions
- Added a new doctest to verify that the view attributes work as expected
- Added new tests for posting to the view
- Added a page test for navigation to the new +frob page.
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.
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.
To demo and Q/A this change, do the following:
Log on as Sample Person (firstname.lastname@example.org:test)
- Click the Frob button
- Observe that the frobnication succeeds
Here's the output of your 'make lint' command. It if is not clean, explain why the reviewer should ignore the lint warnings.