Contents
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 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:
category/port: <write this like a summary/title of the commit log message>
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.
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)
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
See also: FreeBSD Bugzilla Keywords
Flags