Internal FAQ on how we use Trac

  1. How do I get email notifications from TRAC?
  2. How do we use the early statuses?
  3. How do we use the Type field?
  4. How do we use the Severity field?
  5. How do we use the Version field?
  6. How do we use the Site URL field?
  7. How do we use the Keywords field?
  8. How do I keep search engines from finding our dev servers?
  9. Workflow for live bugfix testing and rollout

How do I get email notifications from TRAC?

If you haven't been receiving e-mails from Trac click on the "Preferences" link near the top, then fill in your e-mail address.

How do we use the early statuses?

We're using an initial workflow, and it's still in the evaluation stage, so some of this may still change. The below is sort of the second version, now that we've had some time to work with the system.

  • new: not yet triaged

    When a ticket is marked "new", it means that the reporter isn't sure whether it's a real bug, or doesn't have the authority to make that decision (external tickets are always "new"). If the reporter is one of us, it may still be appropriate to call a ticket "new" until someone familiar with the affected part of the system has looked at it. However, it should be rare for someone other than the reporter to comment on a ticket without moving it out of "new".
  • accepted: acknowledged as a legitimate ticket

    This should be one of the most common states. Anyone who feels they have sufficient clue about the issue is encouraged to mark a ticket accepted. We can also log a new ticket directly into the "accepted" state, since we frequently have in-person conversations that substitute for the triage process.
  • assigned: we know either what needs to be done, or who needs to investigate

    All tickets have owners as soon as they're logged, based on the Component field, but that's a pretty loose association. When a ticket makes it to "assigned", it means that we've confirmed that the owner is indeed the right one to deal with the issue. Sometimes this is obvious because of skill set, and sometimes it may have more to do with resource allocation and priorities; but once a ticket is assigned, it either means "we know what needs to be done and this person is responsible for doing it", or "this person is responsible for figuring out what's wrong".
  • working: the owner is actively devoting time to this ticket

    A given person may have many tickets assigned to them, but the working status lets everyone know which ones are receiving the focus at any given time. This is both to avoid duplication of effort, and to allow high-level monitoring of resources. A developer can have multiple tickets in "working" at once, either because they're related or because they're multitasking, but the goal is to keep the number down to a level that makes the status meaningful.

How do we use the Type field?

Under reconstruction by Ed.

How do we use the Severity field?

See #3345 for the ongoing discussion of this topic.

How do we use the Version field?

This is used to distinguish live bugs from developmental ones. Think about the location of the code that caused the ticket to be logged; if it's on a branch, then it's Dev. If the bug exists on live cnx.org, it's Live. Tasks and Requirements tickets aren't really bugs, so they don't have a version; it can be left blank.

On the reporting side, we will use "Live" to distinguish preexisting bugs that have been moved into a milestone for fixing, as opposed to development to-do's or bugs found in testing. Sometimes bugs are discovered in testing, but not fixed by the end of the milestone; when the milestone is released, those should be changed from Live to Dev (since the bug has moved off the branch and onto the live server).

How do we use the Site URL field?

The Site URL field is for users (or developers) to report where an error occurs; that is, what pages of a rhaptos instance are affected by a given bug. This is particularly important for content. In fact, because the "URLs" are being stored and displayed as simple strings anyway, there's nothing wrong with entering non-machine-readable URLs like "col12345", or "boole 8780 /content/" (see below about the search engines).

For other related URLs, like pointers to web pages that might help with the fix, just use links in the text of your comment. Mockups can be linked to from the comment text as well, or you can attach them directly to the bug.

How do we use the Keywords field?

The keywords field is used to cut across field lines and/or highlight a subcategory of a broad component. For one developer's explanation of the use of keywords in our trac system, see her blog posting on rhaptos.org. The posting also has information about keywords in current use.

How do I keep search engines from finding our dev servers?

When referring to a dev server, use syntax like yoda 8680 /help/reference, or depot 8080 /content/m10020/latest. We'll know what it means, but it's not a followable URL. Note that these can go just fine in the Site URL field, and should, if appropriate -- it's all just strings.

Workflow for live bugfix testing and rollout

The developer on a live bugfix is responsible for finding out from Kathi how important it is, and placing it appropriately in SVN. When a live bugfix ticket goes into testing, it should be placed in the Hot Fixes milestone and assigned a rollout priority in consultation with Kathi. These are collected in the Fixes ready for rollout report.

Details

We've had issues sometimes with live bugfixes getting buried on branches with continuing development, and having to be extracted for separate release. Ross, Kathi, and I met briefly and came up with the following plan.

When a developer starts to work on a new live bug, s/he should check with Kathi to see if its fix should go in with other current development, or be kept separate for priority rollout (either in its own branch and/or devset, or directly on trunk, depending on the scale of the fix).

In the second case above, the ticket should be in the Hot Fixes milestone, rather than in an ongoing development milestone (even a "post-(other milestone)" one). Hot Fixes tickets in testing status are ones that are ready for rollout.

The Priority field is normally the development priority for a ticket; it communicates to the developer which tickets should be worked on soonest. But in the special case of tickets in (1) the Hot Fixes milestone and (2) the Testing status, the Priority field will designate the rollout priority. "High" priority will mean that it should be tested and rolled out ASAP, along with any other accumulated fixes on trunk as appropriate. Our desire will be not to have anything in this state for more than a week. "Critical" will mean we shouldn't hold up even for other accumulated trunk fixes, and only the product(s) affected by the critical fix will be tested and rolled out. "Medium" and "Low" priority are for those gradually accumulating fixes.

The changes from previous procedure are therefore:

  1. Check with Kathi before you commit a live bugfix to an ongoing development branch.
  2. If it turns out to be a candidate for separate rollout, place it in the Hot Fixes milestone.
  3. When it goes into testing, give it the appropriate rollout priority.