Show pageOld revisionsBacklinksBack to top This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ====== 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: <code> 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 </code> * **quality assure** the patch, for example: <code> portlint: OK (looks fine.) testport: OK (poudriere: 132amd64, 132aarch64, DEBUG option tested) unittest: OK (123 passed in 10.5 seconds) </code> * **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: <code> "Assign to myself" "Re-assign" "Approved" "Reset assignee" </code> * 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}} bugzilla/dosanddonts.txt Last modified: 2023/10/14 08:40by GrahamPerrin