h1. Triage process

It's important for us to maintain our Redmine instance, ensuring that issues filed in it accurately represent the known status and have all the necessary data present for developers to solve them.

Most of the issues that get filed need some sort of triage when initially created, as they may be missing information, not filed in the correct project or category, or might be duplicates or related to another issue already in the system.  Doing this as issues are filed is usually best, so we don't end up with a backlog and so submitters get a quick response (particularly where an issue is already fixed, or more information is required).

The second area where issue triage is important is after they've been in the system for months or years.  It's common for issues to have been resolved by later work, either directly (exact duplicates) or by related or larger work (e.g. refactors or redesigns), so returning and checking up on existing issues is useful to keep the overall issue count down.

h2. Pre-requisites

Anybody doing triage work should ensure they have at least "Developer" level permissions in the project(s) they're working in, or "Moderator" level.

h2. Triaging new issues

It's recommended that you enable e-mail notifications for projects you're working on (http://projects.theforeman.org/my/account), or all projects.  A threaded e-mail client helps a great deal too in managing these.

Check:

* That you understand the *issue description*, and either edit and clarify it or add comments to clarify it.

* That the *issue subject* concisely describes the issue, and edit it if not, ensuring it's useful in searches.

* That the issue is filed in the *correct project* (particularly Foreman API versus Hammer CLI, or Foreman vs Installer or SELinux)

* If the user says "errors", that we have a copy of the *full and exact errors*, with complete backtraces and logs (especially for API or CLI issues).

** Asking the user to upload @foreman-debug@ output, as it's useful to collect logs and version info.  Note that if they upload it to our servers, the relevant logs should be pasted into the issue report as files are garbage collected after 90 days.

The following fields are important:

* *Status:* should be "New" unless it's being actively worked on.  "Feedback" if the issue is resolved in some way, but we want the user to confirm.  "Need more information" when waiting on more information from the user.

* *Category:* should be filled in, e.g. "compute resources" for anything related to virtualisation providers

* *Release:* should never be filled in on new issues, only when fixed (a committer will usually set this)

* *Difficulty:* should only be filled in if you have a reasonable idea, else unset it (new devs may start with "trivial" or "easy" issues, so this should be kept reasonably accurate)

If this is a duplicate of an existing issue, use the related issues are to link it with "Duplicates ... #9999" and then set the status to "Duplicate".  Use Redmine's search, your browser history search and your e-mail client search to find these (for this reason, good keywords in bug subject lines are very powerful.)

Do set related issues if you know any, since this can be very useful if one issue in an area is fixed and we can confirm if related issues either were or can be fixed at the same time.

h2. Triaging old issues

Consider starting with a search of issues in a particular area so you're more likely to find overlap and commonality, ordered by the time they were last updated.  You may wish to co-ordinate efforts with other triagers/moderators (i.e. Claer) to avoid duplication of effort.

Along with the general ideas listed above for new issues, try and ascertain whether:

* The issue is still relevant, whether the feature or code still exists, or if the issue describes a function that is even recommended in Foreman ("best practices" change over time).

* If the issue has been fixed or superseded by other work, and this older issue is now a duplicate.

* Whether the issue was perhaps down to user error or a local environment issue.