This is a quick cheatsheet to help committers, maintainers, and users become more effective contributors.

Items are currently unsorted and most don't include explanations, but most (some?) reasons should be obvious.

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.
• follow 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.
• 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.
• thank people, say please, and ask for things politely
• 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.
• 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)

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] like [MAINTAINER], [UPDATE], [EXP-RUN] and [PATCH] in issue titles
  • [NEW PORT] in title for new port submissions is 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 Signatures at the bottom/end of issue reports or comments.
• include poudriere/QA logs as attachment unless specifically requested.
• be abusive, or use abusive language — commentary is immutable.
• create, or engage in, argument
  • instead, be factual.
• be verbose.
• 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.