Trac Ticketing guidelines

[Juan Manuel Palacios]

On Jul 14, 2007, at 7:56 PM, Chris Pickel wrote:

> 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.


	Even though I agree you have a point here, I still think the  
enhancement Vs. task distinction is rather gratuitous. I guess I just  
need to see more examples to find it useful because I still can't  
justify it. I'm personally inclined to remove the task & contribution  
ticket types and stick to simply defect and enhancement, but I'm  
happy to go by consensus and keep them around even if just a few find  
them useful. I believe the type ticket field is already ignored  
enough, the vast majority of tickets simply go by the default  
(defect) even when some of them don't belong in it:

defect: 5480
contribution: 24
enhancement: 1141
task: 52

	So it doesn't make much of a difference to me to keep the smaller  
two around. I do care, however, about making report filings as simple  
& accurate as possible.

>
>> 	-) 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'.


	Doesn't filing under the "Port Updates" milestone suffice for this?

>
>>  *) 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.


	Very good call! I'd make that particular emphasis at first and then  
extend it a bit more to suggest reading the WIkiFormatting doc in  
every trac installation, it comes in handy. But yes, {{{ }}} code  
blocks should be emphasized on their own.

>
>> 	-) 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.


	I agree with Ryan and you here, but then with Ryan again: I think  
"high", "normal" and "low" should suffice for most (if not all) our  
needs, while also sticking to self-explanatory names (I didn't write  
the current priorities, I also said "wha...?" when first becoming  
acquainted with our trac installation ;-). When you have both  
"highest" and "high", how is what's put in each determined? We want  
to keep this as simple as possible (but not one bit simpler, as  
Albert once said).

	So I'll see about creating the new priorities and what will happen  
to existing tickets with the priorities I'll delete. We can later on  
add highest and lowest if need be, but I would discourage that.


>
>>  *) 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.


	Good suggestion, I'll look into it too.

>
>>  *) 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


	Agree with Ryan here again, "Port Submissions" better describes the  
intent in my opinion (and it also pairs better with the other related  
milestones, "Port Bugs", "Port Enhancements", "Port Updates", "Port  
Requests"). I went ahead and made this one move already!


> Feature Requests => Base Enhancements
> Base Bugs (currently missing?)


	We currently have three milestones meant to group ticket submissions  
against MacPorts sources:

1) MacPorts x.y: release specific, where stuff that has been agreed  
to be worked on for the x.y release should go. I think this milestone  
is clearly defined.
2) Needs developer review: tickets detailing either bugs that can't  
be reproduced or with no agreed on fix, or enhancements/new features  
that spark controversy. They can be moved to the release specific  
milestone once consensus is reached *and* a committer agrees to stand  
behind it to do the leg work. I think this milestone is also clearly  
defined, but the protocol to get tickets out of it might be a bit  
flaky and therefore loosely enforced, suggestions accepted.
3) Feature Requests: I agree we need to refine this. I like the "Base  
Enhancement" & "Base Bugs" idea to group tickets against MacPorts  
sources that spark no controversy (that is, not in "Needs developer  
review") but have no man power to do the leg work (so as to keep the  
release specific milestones clean of stuff that will simply gather  
dust). Two problems I have with the proposed approach, though: I'd  
really love it if we could group these two fine ideas in just a  
single milestone (simplicity is golden!) that conveys the idea of  
"Will be worked on later"; and based on that, I'd like to use a name  
other than "Base", as some users are likely to not know what that  
means. Can you help me come up with a suitable name? I'm a bit sleepy  
already ;-)

>
>>  *) 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.


	I don't think I fully understand what you're suggesting. Only two  
versions? We should definitely encourage users to always upgrade to  
the latest release 'cause we haven't broken backwards compatibility  
or anything, so no need to keep anyone back; even more now after my  
dp2mp-move work, which changed so many strings and paths and  
therefore might make debugging older versions harder. To that effect,  
I've removed all versions up to 1.5.0 and included 1.6.0 to stay  
always on "release" and "trunk".

	However, you're suggesting some kind of aliases that always point to  
the right numbers...? If so, I don't think we'll be able to do it, as  
I haven't seen trac support for this.

>
> 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).


	Yeah, forgot to update that. I'm currently having problems doing it  
though, I've notified Kevin about it so I should be able to change it  
soon (defaulting to 1.5.0).

>
>> 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.


	Into the guide and linked from both the Wiki (current ticketing  
document could be simplified to no more than a link to the guide URL  
for the appropriate chapter/section) and the newticket page, correct.  
However, the latter will require modifying our trac template, so I'll  
have to see about it.

>
>
> Chris
>


	Thanks for the feedback, Chris and Ryan! Regards,...


-jmpp