====== 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:
* [[https://bugs.freebsd.org/bugzilla/query.cgi|search]] first — avoid duplication.
* before submitting (saving), double-check the 'Description' field
* you cannot preview what will become your opening comment — [[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=250699|bug 250699]]
* saved commentary can be neither edited, nor deleted — [[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=191677|bug 191677]]
* if the description involves an attachment that aims to patch ''%%doc%%'' (documentation), ''%%ports%%'', or ''%%src%%'' ([[/Base|base]]), write it as you would a good commit message. A ports example:
category/portname:
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 [[https://www.freebsd.org/platforms/#_supported_platforms|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 [[https://bugs.freebsd.org/bugzilla/userprefs.cgi?tab=account|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 [[Ports/QuarterlyBranch|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 [[https://freebsdfoundation.org/freebsd-project/resources/how-to-submit-a-bug-report/|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 [[https://en.wikipedia.org/wiki/Golden_Rule|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 [[https://github.com/freebsd/|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 [[#goldenrule|Golden Rule]])
* be abusive, or use abusive language — commentary is [[#immutable|immutable]].
----
{{tag>HowTo Ports}}