<!> This is now documented in the Debian web site, and as such, this page might need cleanup now.

Context

Aside from the set of global tags (such as lenny, fixed-upstream etc.), the BTS also supports putting free-form tags on bugs. Such free-form tags are called 'usertags' and are always associated with a 'user', identified by an email address. The email address is not important and doesn't even need to be valid. It just provides a namespace for the tag to exist in. This means there is no need to co-ordinate a central list of tags (and that there is no way to get a list of existing tags).

Usertags can be used for 'personal' tags, but are more usually used to help teams manage 'their' bugs. In that case, a list address may be used, for example as in:

Add usertags to bugs

Currently the best documentation on using usertags is the original announcement by aj - perhaps this information should be copied somewhere and maintained (perhaps here?).

You can tag existing bugs by sending email to control@bugs.debian.org of this format:

user user@domain.tld
usertags <#bug> <tagname>
usertags ...
...
thanks

or using bts command (from devscripts package):

bts user 'user@domain.tld' , usertags <#bug> <tagname> , usertags ... , ...

Using a colon in the email to control@d.o will result in errors. Eg:

Produces Unknown command or malformed arguments to command.

You can also set a usertag in an initial email to submit@bugs.debian.org:

Package: foo
Version: version
User: user@domain.tld
Usertags: tag

bugreport...

Display usertags on the web BTS view

You're half-way now; it you want a nice packages bugs list like devscripts (with tag to group up bugs), then you need to use usercategory in an email to control@bugs.debian.org (some more information):

user user@domain.tld
usercategory <cat-name>
 * <place a name here> [tag=]
 + <tag1> [<tag1>]
 + <tag2> [<tag2>]
   ...
 + <tagN> [<tagN>]
 + Uncategorized []
usercategory normal
 * status
 * <cat-name>
 * severity
usercategory <pkg>-sort
 * status
 * <cat-name>
 * severity
usercategory old
 * status
 * severity
 * classification

To view the bug page thus ordered, you simply can add the following to your query URL:

 ;users=user@domain.tld;ordering=<category name>

where user@domain.tld is the name used above (defaults to <pkg>@packages.debian.org) and <category name> is one of the categories above (defaults to normal).

Display usertags on the default BTS package view

Use <pkg>@packages.debian.org as user@domain.tld (only if you are actually from that team).

  1. pay attention at the order you write the tags in the usercategory, since it will be the same order the tags will show up on the BTS page.

  2. when you add a tag to bugs, you need to modify the usercategory to treat that tag too (I don't like this, but that's the way it is).

  3. you can add a usertag to usercategory even if no bug is usertagged (yet) with it: it will appears as soon a some bugs will have that usertag.

  4. usertag name can have only alphanumerics, at, dot, plus and dash, while <cat> in <cat> [<tag>] can have underscore too (maybe other chars, untested).

Comments

Comments about usertags can go on this page...

from #debian-mentors:

<pabs3> ooh, usertags
<pabs3> bts++
<Nigel> pabs3: i thought it was a random users suggestion at first, was about to reply, "HAHAHA, they will never do that"
<pabs3> :)
<pabs3> aj does roxor
<Nigel> yeah
<Nigel> i must go and set usertags on all my bugs now...
<Nigel> i must say the following though: it'd be nice for the maintainer to get a copy of all tags set...
<pabs3> yeah, indeed
<Nigel> also, it'd be nice if there was a link up the top now, with "Maintainers Tags"
<Nigel> or (dunno if this defeats the purpose) set it up so tags set against the maintainer's email address, or the package@packages.d.o addy shown by default...
<pabs3> even better, add a thing to reqest@ for advertising usertags by default for a certain user/package/etc combo
<pabs3> adding it to the wiki page :)


One could add a option to the CGI to select a predefined categorisation class. I would like to say something like

 Example 1:
 ...;class0=Status;nam1=myown;pri1=...;ttl1=...;class2=Severity

Another useful addition could be to be able to globally rearrange the ordering of the categories. If I have used example 1 and now I want to rearrange the categorisation to move Severity to the top level I currently would have to do that (we assume for a moment the class parameters would actually work):

 Example 2:
 ...;class1=Status;nam2=myown;pri2=...;ttl2=...;class0=Severity
 better:
 ...;class0=Status;nam1=myown;pri1=...;ttl1=...;class2=Severity;ord=1,2,0

Here my first tries with categorisation together with usertags:

by ?FrankLichtenheld


It would also be very nice to use the package a bug is filed against to divide them into sections. I'd like to use something like this:

   tag=proposed-orphan,proposed-removal;
   users=debian-qa@lists.debian.org;
   ...
   nam1=Status;pri1=pkg:ftp.debian.org,wnpp;
   ttl1=Pending removal,Waiting for adoption,No answer yet;
   ord1=2,1,0

by ?MarcBrockschmidt


(This is done.)


--?AdeodatoSimo



Here's a useful view in the BTS: http://bugs.debian.org/cgi-bin/pkgreport.cgi?tag=security;users=debian-security@lists.debian.org;ordering=tracked