Commenting Bugs and Fixes
Last updated at 6:13 pm UTC on 14 March 2007
Now any Bug, Fix, or Enhancement report should be made by entering a new issue in the Squeak Mantis Database at http://bugs.squeak.org/. Goodies and announcements can still be sent to the Squeak Mailing Lists.
Generally, any bug report or bug fix should apply to the latest alpha version of the Squeak image (for example, 3.9alpha). If you find a bug in the current stable image (e.g. 3.8), you should check to see if the bug has been fixed in the latest alpha release before posting a bug report/fix.
For details on how to submit new reports to the Mantis database please read our project documentation at http://bugs.squeak.org/proj_doc_page.php.
The purposes of commenting on a submission are to:
- Improve it by feedback and fixes
- Help the community and Harvesters know both that it matters (you help to decide this!) and that it is ready.
Some specific kinds of feedback are considered useful. In particular, the community and the Harvesters will look for QA tags in the subject line of an email. The QA tags are:
[sm] Small. (Changesets should be under 10k.)
[cd] Changes Documented (Reasoning is given that explains every change made)
[sl] SLint approved (You don't have to do what SLint says(sometimes it's wrong), but have a good reason why you didn't)
[er] Externally Reviewed (Design + code, by someone other than the author, preferably knowledgeable about the package. See c2.com/cgi/wiki?DoTheSimplestThingThatCouldPossiblyWork and related pages)
[et] Externally Tested (Import into a fresh image; generally making sure it doesn't break anything that uses it; run relevant existing SUnit tests. (Implies [er] and[cd])).
[su] Covered by and passes SUnit tests, either included or external. Included tests should be described, and external tests should be pointed to.
Note that these specific tags have two purposes -
- Make life easier for The Harvesters, in order to make the Harvesting Process faster. (This is Step #2 of the Harvesting Process.)
- Raise our standards. You'll note that one of the tags that we really want people to use is the SLint tool. Yes, it's a new tool, but it often brings to one attention things like "now that you mention it, maybe a shorter method would be better". So please, use the tags, even for very short updates.
Now for the technicalities - how does one post a comment?
By far the best way to post a comment is to use the BFAV (Bug Fixes Archive Viewer) tool to view and comment on fixes, which takes care of the technicalities for you. It also allows you to easily view/filter/browse all submissions and their comments, so you can find other stuff that interests you.
If you want to post a comment "manually", you can submit comments on a [FIX] or [ENH] post simply by sending a correctly-formatted post to the Squeak Mailing Lists. As of 3/7/2003, the Bug Fixes Archive will group "comment" posts with the original post iff the comment post's subject line starts exactly the same as the original post's subject line. (An "Re:" at the beginning is allowed by the second generation BFAV2.)
For example, if J. Squeaker posted
[FIX] Glue HumptyMorph Back Together Again
to the list, and you want to comment, start the subject line of your post with exactly this:
[FIX] Glue HumptyMorph Back Together Again
Then, append your comment inside one set of parentheses:
[FIX] Glue HumptyMorph Back Together Again (Great work! I can't believe that he's fixed)
In our running example, the use of qa tags will look like:
[FIX] Glue HumptyMorph Back Together Again ([et] Great work! I can't believe that he's fixed)
Definitely do not nest any parentheses inside your comments. If your subject line looks like:
[FIX] Glue HumptyMorph Back Together Again ([er] Cool! Looks good (reviewed quickly - ([sm][sl)))
you will severely confuse the Bug Fixes Archive and your comments will not get in correctly.
After you post bug report comments to the Squeak Mailing Lists the first few times, go look in the Bug Fixes Archive and make sure that your comment got in.
Remember that the tags should convince The Harvesters to look inside, and that inside, they expect to find details. If you're doing a review, explain the code/changes/design/tradeoffs, so The Harvesters don't have to wonder about them. If you're testing, explain your coverage, or include SUnit tests. The Harvesters will add tags too, when they look at things, to either note something is accepted, rejected, or requires something else.
See also How to help with harvesting - Simple things we can all do
How QA Tags are used
Starting 3/7/2003 The Harvesters will be harvesting things directly from the Bug Fixes Archive, as part of a new Harvesting Process. The Harvesters will prefer the fixes that have tags showing they'll be quick to process.
For example if The Harvesters see -
[FIX] Save the world!!
John Doe (2/3/03)
and
[FIX] Adjust the background to a paler shade of gray
Jane Doe (2/3/03)
Joe Shmoe (5/3/03) ([et][er] - it's beautiful)
the "Adjust the background" [FIX] will get preference for harvesting.