Bugzilla DO's and DONT's
To help people become more effective contributors.
Are you an issue tracking champion? Test yourself …
DO's
All Users
Do:
search first — avoid duplication.
- before submitting (saving), double-check the 'Description' field
you cannot preview what will become your opening comment — bug 250699
saved commentary can be neither edited, nor deleted — bug 191677
if the description involves an attachment that aims to patch doc (documentation), ports, or src (base), write it as you would a good commit message. A ports example:
category/portname: <short summary> Introductory paragraph or sentence establishing context or background * Verb $change1, $reason (why) * Verb $change2, $reason (why) [1] * Do this, because that. Optional final words, sentences, or paragraphs about impact, conclusions, caveats, implications, or extra context. [1] https://SomeExternalReferenceOrLinkLikeABugOrCommit
quality assure the patch, for example:
portlint: OK (looks fine.) testport: OK (poudriere: 132amd64, 132aarch64, DEBUG option tested) unittest: OK (123 passed in 10.5 seconds)
test at least all supported major versions, including one each of Tier 1 amd64 and aarch64.
ask Bugmeister if you have any Bugzilla-oriented question, or if something is unclear.
prepare/test/finalise/QA patches before submitting them.
set Product and Component fields as accurately (specifically) as possible.
set Firstname Lastname in Preferences for credits in commit messages
inform other people if you think they can help, or because it might be relevant to them. Examples:
- CC python@ for Python ports, ruby@ for Ruby ports
Set maintainer-feedback ? <their-email> if they are responsible (maintainer) or main/recent contributor of something
use and update metadata fields like Depends On:, Blocks:, URL: and See Also:
prefix Ports issues with $category/$portname: $Summary.
format Summary correctly:
New Ports: [NEW PORT] category/portname: ${COMMENT}
Port Updates: category/portname: Update to ${PORTVERSION}
Adopt a Port: category/portname: Take MAINTAINER'ship
write Summary like a good commit message summary/title/shortlog for port/base issues with patches
keep Summary and other metadata fields up-to-date, reflecting the latest issue status, if and when that occurs.
think about how to write the Summary line. Yes, it's an art-form.
use concise and clear Attachment descriptions.
- make as many changes on an issue at a time as possible, not one by one.
separate fixes from version updates into individual issues (or patches), so they can be merged to the quarterly branch
set maintainer-approval to ? <maintainer email> on attachments you submit for ports you are NOT maintainer of
Note: maintainer approval requests must include the maintainer's e-mail address as specified in the port's Makefile
- post a comment if you're unable to provide requested feedback (eg. due to lack of time or even loss of interest)
be polite — say please, thank you, and so on
be patient
the 'Following Up' section of How to Submit a Bug Report describes periods during which there is no visible activity on a report
invisible activities include thought processes, and other things that are not easily expressed in plain text
if visible work towards a fix takes longer than you would like, remember that most work is volunteered, and that each person contributing (including upstream) will have priorities that do not match your own.
remember the Golden Rule
- treat others as you would like others to treat you — what you wish upon others, you wish upon yourself
apply the rule equally in areas that run parallel to Bugzilla, such as the FreeBSD Project organisation in GitHub.
Maintainers
Do:
make sure MAINTAINER=<email> matches Bugzilla account <email>
set maintainer-approval to + on attachments for ports you are MAINTAINER of.
Committers and Triagers
Do:
assign yourself to issues as early as possible (ie: not after committing/fixing).
add original Assignee to CC: field when Re-assigning.
- assign yourself to an issue if you Close or Resolve it.
assign yourself to an issue if you are the Reporter and a Committer, if the MAINTAINER is not also a Committer
use the correct/closest Resolution possible.
Note: FIXED means a change (commit, etc) was made to fix this, not this issue is fixed.
change an issue status from New to Open once Triaged or Assigned.
DON'TS
Please, do not:
use the patch or patch-ready keyword
use [tags] such as [maintainer], [patch], or [update] in the summary line (the title)
[exp-run] and [new port] are OK, for now
use an empty summary
use foo is broken as a summary
add just me too comments. DO add comments if you have additional information
bump issues (add "bump" or "any progress?", etc)
instead, do update issue metadata to bring it up to date
do include comments if they clarify what is now needed to progress the issue
speculate on what an issue/bug is caused by. Stick to facts and evidence
fiddle with Attachment mime types
- cancel/remove a flag by setting its value to empty/undefined
paste large logs or file contents in comments (DO: use Attachments)
- include poudriere/QA logs as attachment unless specifically requested
wait for others to add or update issue fields. Many hands make light work
add a Comment if the change made is self-explanatory. Example:
"Assign to myself" "Re-assign" "Approved" "Reset assignee"
instead, add a Comment with an explanation if the change isn't (by itself) self explanatory. Example: Reset assignee, no longer maintainer
try to game the system. Example: by adding easy patch-ready or setting approved flags
use maintainer-feedback flag to declare approval of a patch. (DO use the maintainer-approval flag)
combine or include patches for multiple ports in the same issue, unless they *must* be committed together
instead, create separate issues and have them Depend on or Block each other as appropriate
- change the status of an issue to past Open (eg: In Progress) unless and until it has a real (not a team or mailing list) Assignee
this criterion does not suit all workflows, should probably be mentioned at KubilayKocak/Bugzilla/ProblemsAndIdeas
- close (resolve) an issue until all commits/changes have been made (including MFC's and MFH's)
use external URL's in comments, as they can become stale/disappear
- instead, include URL contents as attachments with the URL as the Description, or in the URL or See Also fields. All information should be self-contained in the issue
use the same PR to do multiple unrelated things. E.g: if while working on a fix for a port a new version is released, create a new PR to update the port
include Signatures at the bottom/end of issue reports or comments
- be unnecessarily verbose
- create, or engage in, argument
- instead, be factual
disagreement is natural — when a technical difference of opinion arises, do, please, build and maintain mutual respect (remember the Golden Rule)
be abusive, or use abusive language — commentary is immutable.