Trac Ticketing guidelines

[Chris Pickel]

On 14 Jul, 2007, at 19:20, Juan Manuel Palacios wrote:
> 	-) enhancement: tickets with or without patches that simply aim to  
> enhance something that's not necessarily failing (which would be a  
> "defect");
> 	-) task: have never been able to differentiate this too well from  
> enhancements above... I could argue that whatever task is worthy  
> enough to be put into a ticket as a request can be considered an  
> "enhancement" request (but of course, project members are allowed  
> to determine it's not a worthy enough enhancement and reject the  
> ticket ;-); this interpretation renders the enhancement Vs. task  
> distinction unnecessary, so please do come up with your own  
> interpretation if you have one;

My understanding of the difference between these is that an  
enhancement is something that goes /into/ the repository, whereas a  
task is something that's done /to/ it. For example, requesting an  
update to port 'foo' is an enhancement, whereas requesting that 'foo'  
be renamed to 'libfoo' is a task.

> 	-) anything else? I'm not sure if we need some other ticket type,  
> feel free to suggest;

It might be worth distinguishing 'enhancement' and 'update'.

>  *) Full Description: Where the gritty ticket details should go,  
> currently not listed in the TracTicketing doc;

I think a point should be made that excerpts from the log should go  
in {{{ }}}. It's very hard to read tickets where a user has posted a  
log inline with the description, because all sorts of WikiSyntax gets  
triggered.

> 	-) Expected: for most reports on port build failures, users are  
> free to *expect* these to be fixed;

I always felt this name was odd. To me, it implies a sort of  
indifference to the bug: "we expect it'll get fixed sooner or later."

Colloquy's Trac simply defines these as "highest", "high", "normal",  
"low", "lowest" (defaulting of course to "normal"). This seems much  
clearer and perhaps more useful than our current system.

>  *) Component: Currently listed in the existing doc, but limited to  
> "ports" and "base"; those two are keepers, but:
> 	-) "uninstaller" and "dp-cocoa" are deprecated and shouldn't be  
> listed, I've only not removed them 'cause of legacy reasons as  
> there are some tickets filed against them;

Maybe merge them into a 'deprecated' component? I'm sure no one would  
file new tickets against that.

>  *) Milestone: this is easily one of the most important fields in a  
> ticket, proper usage will allow us to find them quicker simply  
> because the roadmap is almost everyone's starting point. On the  
> choices available:

Seems like a bunch of these are only for a single component  
(particularly ports). Maybe some naming could be standardized for  
this? i.e.

New Ports => Port Additions
Feature Requests => Base Enhancements
Base Bugs (currently missing?)

>  *) Version: fine as it is now, but maybe a good addition is  
> explaining that this field is irrelevant in some cases (like when  
> filing tickets for the guide), whereas it's crucial in some others  
> (a bug report against MacPorts sources);

A possible improvement, although more work, would be to add "release"  
as the new default, and "trunk". When tagging 1.5.1, the "release"  
version would be renamed "1.5.0" and a new "release" version created.

Under that system, users would only ever have to change the setting  
if they're running trunk, in which case they probably already know to  
do so. On the other hand, I suppose it would be sufficient to keep  
the default argument up to date with release (it still seems to  
default to 1.4.40).

> I also believe a higher degree of formality for this type of  
> documentation is in order, therefore I think this is the perfect  
> example of what should be moved out of the Wiki and into the new  
> guide.

It should go anywhere it will be seen by bug reporters before they  
post, but I don't know where that would be. Probably being linked off  
the New Ticket page is the only guarantee.


Chris

-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 186 bytes
Desc: This is a digitally signed message part
Url : http://lists.macosforge.org/pipermail/macports-dev/attachments/20070714/09a3f712/PGP.bin