Documentation
Traditionally, debbugs has divided lists of bugs by "status" (whether the bug is outstanding, forwarded, done, etc) and by "severity" (critical, grave, etc), and allowed pretty minimal manipulation of this -- basically the ability to reverse the order of various things.
Usertags enables a different approach, since sorting by "tag" suddenly becomes particularly useful and interesting.
The approach then, is to have a small evaluation language that allows you to match individual bugs to a section. A section is then defined by a sequence of expressions such as "pending=forwarded,severity=grave", and collates all the bugs that match the expression. The introduction of tags makes this slightly more complicated however, due to the fact that we might want to define one section by "tag=fixed" and another by "tag=patch", but then we need some way to tell debbugs which section should be home to a bug with both the "patch" and "fixed" tags.
The way we resolve this is by giving sections two orders: "importance" and "display". So we might want to have sections for patched bugs, pending bugs, fixed bugs, and wontfix bugs -- but we need to check for those tags in the order of "fixed,pending,wontfix,patch" -- since, eg, there's no point worrying about a "patch" tag on a bug that's not going to be fixed, nor is there any point worrying about a "wontfix" tag on a bug that has already been fixed or marked pending. The specification for this example is then:
- pri0=tag:fixed,pending,wontfix,patch ttl0=Fixed in NMU,Pending upload,Will not fix,Patch proposed,Unresolved bugs ord0=3,4,1,2,0
Note that ord is 0-based, and both ttl and ord may have one more entry than pri -- this is the catchall for things that don't match any of the listed requirements. If a number is missing from ord, bugs in that category aren't displayed.
Beyond this, a hierarchy is often required -- you want to order bugs first of all by whether they're open or closed, then by how serious they are, and perhaps then by whether the bug has a patch, is confirmed, is marked wontfix, or similar. This is done by bumping the "0".
In some cases you might not want to create sections based on a single field. In such cases you can use long hand notation, so the above was equivalent to:
- pri0=tag=fixed,tag=pending,tag=wontfix,tag=patch
If you wanted to look for self-contradictory bugs, you might have sections such as:
- pri0=severity=grave+tag=unreproducible,tag=pending+tag=wontfix
Ideas
Some ideas.
- How about handling or as well as and? If I want a section for release critical bugs, there's no way to say "severity=critical|severity=grave|severity=serious". Shouldn't there be? If we're adding an or, should we add a not and parentheses too? Maybe RPN would be better -- then you could assume that "+" is a separator, and that there's an implicit "and-rest-of-stack" operator at the end, and you don't have to worry about brackets. I don't think there's any point worrying about "=" being infix already, "severity=foo" is pretty much atomic. I'm not sure what you would do about real operators, but this might plausible:
- pri0=severity=critical+severity=grave+severity=serious+@or+@or+tag=wontfix
- Matching on package= would probably be useful. Ditto source=. I guess daysold might be useful, if there were a comparative operation rather than just equality. owner= would probably also be interesting, though probably requires the following feature too.
- Some sort of "pri0=severity:*" syntax would be good just to get severities in their default order. Generalising would be good too, to get packages in their default order, etc. This would have to imply answers for "ordX" and "ttlX" too, rather than allowing them to be specified. Maybe "def0=severity" would work.
- Also nice would be for a "user" to set a "favourite" sectioning hierarchy, or even multiple ones. So that you could divide a packages bug up by "functional area", or by "who's workingon what", or "how important bugs actually are". It'd be nice to include links to these views in the bug page that users see, to some degree.
- Currently you can specify stuff in the command line, or set cookies using a form and some javascript. We want something that can be more easily shared though -- which probably means a control@ interface. It's not quite clear what that should be; and probably there should be a little more simplification of the syntax first anyway.
request@ interface
Err, this isn't implemented yet.
By example:
user licensing@release.debian.org usercategory licensing-problems [hidden] * License [tag:] + GNU Free Documentation License [1:gfdl] + Open Publication License [4:opl] + Other License: Unmodifiable [2:unmodifiable] + Test [5:do-not-take-serious] + Unknown license, wtf [3:] usercategory djpig-1 * severity * licensing-problems * status
Some notes.
Unless you specify [hidden] your usercategory will show up in the drop down list in Options
- You can reference other usercategories you've defined as a level
- Otherwise, you specify a name, and a prefix in square brackets
- You then specify each category, by putting a plus sign, a description, and in square brackets the order number, a colon and how the category is defined
The order number's optional; if it's not specified, it'll appear in the order listed (after any entries that do have an order specified though) -- eg, Test [do-not-take-serious]
The description's optional. You can either say + [do-not-take-serious] which means those bugs won't be displayed at all; or you can say + do-not-take-serious which will have a (crap) description generated for you automatically
How should this be stored?
Category: licensing-problems Hidden: yes Cat1: License Cat1Prefix: tag: Cat1Options: gfdl - GNU Free Documentation License opl - Open Publication License unmodifiable - Other License: Unmodifiable do-not-take-serious - Test Cat1Default: Unknown license, wtf Cat1Order: 1,4,2,5,3 Category: djpig-1 Cat1: severity Cat2: licensing-problems Cat3: status
And as well as this we need a data structure that can hold the information in memory. What should it look like?
$user->{"category"} =
{ "licensing-problems" =>
[ {
"nam" => "License"
"pre" => "tag:",
"pri" => [ "gfdl", "opl", "unmodifiable", "do-not-take-serious" ],
"ttl" => [ "GNU Free Do...", ... ],
"def" => "Unknown license, wtf"
"ord" => [ 1, 4, 2, 5, 3 ]
} ]
"djpig-1" => [ "severity", "licensing-problems", "status" ],
}
$user->{"visible_cats"} = ["djpig-1"]