Issue tracking is **all** about repeatedly asking //What does this issue need to progress?//
  * If it hasn't been done, do it, or ask for it, or triage (classify) it accordingly.

===== High Level Goals =====

  * As a Triager/Committer: Get issues **Assigned** quickly and accurately
  * As a Project/Maintainer: Get issues **Resolved** as quickly, accurately and completely (permanently) as possible
  * As a Maintainer/Contributor: 
    * When providing a patch, no open questions about the proposed change.
    * No open questions about what's needed to progress the issue (what, why, when, how, where.)

===== Checklist (Definition of Done) =====

An issue is 'ready' when the major pre-requisites are satisfied:

==== A clear summary and proposal ====

  * ☑ Has a Title that is clear and describes either the 'issue' (bug) or 'the proposed change'
  * ☑ All issue detail and metadata is 1) accurate 2) up-to-date and 3) complete.

==== A proposed change as a patch ====

  * ☑ Has //one (1)// changeset (patch)
    * ☑ Has an //Attachment// of type: //patch// (Attachment 'Details -> Edit Attachment -> ☑ Patch)
    * ☑ In unified diff format. ''%%git diff%%'' is preferred, or ''%%diff -u%%''.
    * **All** other patches are marked //Obsolete// (Attachment 'Details' -> Edit Attachment -> ☑ Obsolete).

==== No open questions or ambiguities ====

  * ☑ Has no outstanding questions or ambiguities about who, what, when, where how, or why a change is needed
    * The ''%%needs-qa%%'' keyword should be removed if it is set and all questions have been answered and related flags acknowledged (? -> +)

==== Has been tested ====
  * ☑ Has been QA [[#Change_has_been_Tested|tested]] and confirmation that QA passed is included in the Description/Comment
    * The ''%%'needs-qa%%'' keyword should be removed if it is set and QA testing has been completed and confirmed.

==== Has approval, if required ====

  * ☑ Has "approval", if required. Any of:
    * Patch has //maintainer-approval// flag set to //+// by the port MAINTAINER even if the maintainer is also the submitter
    * It has been > 14 days since last request for maintainer-feedback (flag) was requested (set to ?)
    * It has been > 14 days since last request for maintainer-approval (flag) was requested (set to ?)
    * Port is unmaintained (MAINTAINER=ports@%%FreeBSD%%.org)

===== General =====

  * //Summary// field clearly and succinctly //summarises// describes the changeset. Eg:

<code>
category/port: <write this like a summary/title of the commit log message>
</code>

Additional summary tags:
  * DO Prepend the summary with ''%%[NEW PORT]%%'' if the changeset introduces a new port.
  * DONT use any other [TAGS]. Use the correct bugzilla field instead:
    * Attachment -> Details -> Edit Details -> maintainer-approval [+] for patches to ports you maintain

  * //Description// (Comment) field contains list of changes and their rationale/explanations formatted like a commit log message. See example below.
  * //Description// (Comment) field includes explicit confirmation that QA has been run and passes. See example below.
  * For port version updates, //Description// field contains a //Changelog:// line with URL pointing to changelog. See example below.

<code>

 category/port: <write this like a summary/title of the commit log message>

 * Remove files/patch-<foo> (upstreamed) [1]
 * Fix variable assignment (pet portlint)
 * Remove <foo> (fix build problem on <version> <arch>)

 Changelog:

   <URL to changelog>

 [1] Upstream reference URL (pull request, issue, mailing list)

QA:

  * portlint: OK (looks fine.)
  * testport: OK (poudriere: <versions>, <archs>, <OPTIONS> tested)
  * maketest: OK (XXX of XXX tests PASS)

</code>

  * If an issue depends or blocks another, //Depends on// and/or //Blocks// fields are set correctly.
  * Flags have been set if appropriate.
    * If a security or build fix, set //merge-quarterly// to //?// so that it can be tracked.
    * If it needs wider ports testing by portmgr@, set //exp-run// to //?// so it can tracked.
    * If maintainer feedback (not approval on a patch) is required, //maintainer-feedback// is set to //?// %%<%%maintainer-email>.
    * If you are the maintainer of a port you are updating then set the //maintainer-approval// flag to //+// (on attachments).
  * If its a Security issue, ports-secteam@ is CC'd, and the //security// keyword is set.

===== Change has been Tested =====

The proposed change successfully passes Quality Assurance (QA) tests:

  * ''%%poudriere testport%%'' (or bulk -t)
    * Best: ALL supported versions & architectures
    * Good: All tier-1 architectures and supported versions
    * Minimum: Latest major release 'and' i386/amd64
  * ''%%portlint -AC%%''
    * Alternatively: ''%%USE_PORTLINT=yes%%'' in ''%%LOCALBASE/etc/poudriere.conf%%'', portlint output will be in poudriere.log
  * Bonus:  Add ''%%DEVELOPER=yes%%'' is enabled in //etc/make.conf// for extra QA checks

===== Keywords =====

Issue is completely and accurately annotated with [[Bugzilla/Keywords|Bugzilla keywords]]

  * See also: [[https://bugs.freebsd.org/bugzilla/describekeywords.cgi|FreeBSD Bugzilla Keywords]]

===== Flags =====

----

{{tag>HowTo Ports}}