To help people become more effective contributors.

Are you an issue tracking champion? Test yourself …

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.

Do:

• make sure MAINTAINER=<email> matches Bugzilla account <email>
• set maintainer-approval to + on attachments for ports you are MAINTAINER of.

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.

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 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.