• Bugzilla
• DosAndDonts

Bugzilla DO's and DONT's

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's

All Users

Do:

• Double-check Description before submitting¹.

• ask Bugmeister if you have any questions or something is unclear.

• search before creating a new issue/bug.

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

• write the Description as you would a good commit message if its for port/base issues with patches. 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
    

• include confirmation that the attachment (patch) passes QA in the comment/description. Example:

  • portlint: OK (looks fine.)
    testport: OK (poudriere: 93amd64, 103i386, DEBUG option tested)
    unittest: OK (123 passed in 10.5 seconds)

  • test at least all supported major versions, and one each of i386/amd64.

• thank people, say please, and ask for things politely

• 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)

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] 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. Bugzilla is permanent.

• argue. Bugzilla is permanent.

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

CategoryHowTo CategoryPorts