This page outlines the guidelines developers/bug squad members should follow when triaging issues and working with the issue tracker.
Labels help categorize an issue and allow for easier searching of the issue tracker. Labels should be used if it makes sense, but issues do not need to have labels.
The labels for an issue can be grouped into several categories:
- Component tags (referring to the part of KiCad affected):
- The applications themselves: pcbnew, eeschema, fp-editor, symbol-editor, 3d-viewer, gerbview, pleditor, pcb-calculator, bitmap2component
- qa: anything related specifically to the QA unit test or utilities
- Functional areas:
- router: the routing algorithm
- rendering: the editor canvas
- ui: dialog and interface issues (including usability issues)
- erc: netlisting, connectivity and ERC checking in schematics
- drc: DRC checking in PCBs
- ngspice: circuit simulation
- hotkeys: keyboard interface
- python: Python components (such as bill of materials plugins, python integration, etc.)
- export, import: file export/import
- Specific file formats (usually combined with export or import tags): dxf, gerber, step, svg, vrml, eagle
- documentation: documentation in the source tree
- Platform tags (used when bugs only affect a subset of supported platforms):
- windows, macos, gtk
- Other tags:
- i18n: issues with the internationalization of the program
- starter: bugs suitable for “new” contributors that do not require very in-depth knowledge of KiCad’s codebase.
- regression: bugs that are regressions from the previous stable release of KiCad
- documentation: issues related to the developer documentation
- cleanup: technical tasks that are not visible to users, but still should be addressed.
- packaging: issues related to packaging problems. Only report issues that can be fixed in the core KiCad code, as opposed to downstream packages, which have their own bug reporting systems. This Includes reports of broken builds on specific platforms.
- feature-request: requests for new features to be implemented
- wxwidgets: issues that are solved by upgrading to a newer wxWidgets version or whose root cause is inside wxWidgets.
Multiple labels can be applied to an issue as needed. It is recommended to include a component tag if the issue affects only one component. Some examples of possible labels for an issue are:
- "pcbnew export step" - For issues that affect the export of STEP models from pcbnew
- "pcbnew import svg" - For issues that affect the import of SVG files into pcbnew
- "pcbnew router" - For issues that affect routing tracks in pcbnew
- “eeschema ngspice” - For issues that affect the circuit simulation in eeschema
- “pleditor hotkeys” - For issues that affect the use of keyboard shortcuts in the page layout editor
- "gtk ui" - For issues that affect the user interface on only linux operating systems
Only the official labels listed in this document should be used to categorize the issues in the issue tracker.
New official labels should be simple and usually contain only a single word. Sometimes multiple words are needed (such as 3d-viewer or feature-request), and should generally use a hyphen to separate the words.
The issue status is tracked using the labels underneath the “status::” scope. Only one status should be applied to an issue at a time. By default, issues should be placed into the new status.
The possible status values for issues are:
- new: A new issue that has not been verified yet
- confirmed: The issue has been confirmed by a developer
- need-info: The issue reporter must provide more information about the issue
- in-progress: A fix for the issue is being worked on by the assignee
- as-designed: The reported issue is actually how the program works (equivalent to won’t fix)
- resolved: The reported issue has disappeared/is no longer reproducible (but the commit fixing it is unknown)
- fix-committed: The fix for the issue has been committed to the repository
- fix-released: The fix is included in a release of KiCad
- fixed: The fix was done outside the KiCad code (such as a packaging-only fix)
- opinion: The reported issue is subjective and knowledgeable users may disagree as to whether it should work this way or not
- duplicate: The issue has already been reported
GitLab provides an open/close status for issues as well. Any issue in as-designed, fix-committed, fix-released, fixed, or duplicate should be placed in the closed status, while the others should remain in the open status.
Moving an issue into the confirmed status should be done once the reporter provides enough information to recreate the report and it has been recreated in any of the current development versions on a supported platform.
The as-designed status means that the issue reported is not actually an issue, but instead is how the program is supposed to operate currently. An issue in this status can still be discussed, and if a convincing argument is made, this report could become a feature request for the desired behavior (and move to the confirmed status).
The importance of an issue is tracked using the labels underneath the “priority::” scope. Only one importance level should be applied to an issue at a time. By default, issues start in undecided.
The importance levels are:
- undecided: The issue hasn’t been triaged yet
- wishlist: Not a bug but instead is an enhancement/new feature.
- low: The bug is minor and should be fixed when convenient. These may not be encountered often by users or a workaround exists for them.
- medium: The bug affects usability, and a workaround is either very complicated or doesn’t exist.
- high: Bugs that cause either data loss/corruption or serious UI breakage (resulting in unusability of the program).
- critical: Exclusively for things such as build errors and frequent crashes
The majority of issues will be either wishlist items or of low importance. Bugs should only be escalated to higher importance levels (such as high or critical) if they meet the criteria for those levels.
Small UX issues should probably go on the low importance level. New features are typically Wishlist. Many low priority bugs or simple wishlist items can also be labelled with starter to encourage new developer contributions.
Attaching a milestone to an issue is intended to associate the fix for the issue with a target release. If an issue is present in two branches, target it to the milestone for the older release (e.g. if an issue is present in both 5.1 and 6.0, use the 5.1 milestone). The exception to this is if the fix for the issue will be too invasive to the code or has a high risk of introducing new bugs. In this case it should be targeted at the currently active development branch. When in doubt, target the issue to the older release and revisit the milestone when the fix is committed.
The milestone field should only be set for wishlist and low-priority bugs by the developer who plans to work on that issue. In other words, issues without a developer assigned should generally not have a milestone unless they are medium priority or higher.
For major releases, we may have two milestones open at once: A feature freeze milestone and one for the actual release (typically the first release candidate, like
6.0.0-rc1). Feature requests, wishlist items, and tasks should be targeted to the feature freeze milestone, which should have a due date before the release candidate. Bug reports should be targeted to the release candidate. This way, the feature freeze milestone shows the remaining work until feature freeze, and the release candidate milestone shows the rest of the work that can be done before or after feature freeze.