Trac Ticketing guidelines

[Juan Manuel Palacios]

	Hi Maun Suang!

	Since you're the one who has been amending the TracTicketing doc up  
at our Wiki recently, would you mind if I embark you on a rewriting  
task? ;-)

	From a quick skim over the doc, it seems to me like the "How to file  
a ticket" section still reflects much of our Bugzilla practices back  
in OpenDarwin days, and these mostly don't apply to current times any  
longer. It would be great if we could rewrite it to reflect our  
current practices and trac ticket fields (following in order, per the  
entries in standard new ticket submission):

  *) Short Summary: from the current wiki entry:
	-) first summary part: there's no longer a need to use summary  
keyword prefixes to make it clear from the start what the ticket is  
about (see milestones below);
	-) second summary: make that "<port> <version>" or "base <version>",  
as it currently only talks about <version>, from what I could  
understand;
	-) third summary part: keeper

  *) Type: Probably one of the most neglected ticket fields (its drop- 
down menu should definitely be larger!):
	-) defect: for any port/MacPorts build/runtime failures and/or  
documentation corrections;
	-) 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;
	-) contribution: something I created a while ago but still haven't  
gotten too used to; I originally conceived it as "enhancement  
requests *with* patches incorporated", but getting so fine grained  
might not bee such a good thing (ignored enough); I'm thinking about  
removing it if nobody can come up with something good to justify it  
(I know I, its creator, can't ;-)
	-) anything else? I'm not sure if we need some other ticket type,  
feel free to suggest;

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

  *) Priority: currently not listed either (the following are just my  
appreciations on what we should use each of these for, feel free to  
suggest/correct):
	-) Expected: for most reports on port build failures, users are free  
to *expect* these to be fixed;
	-) Important: for MacPorts build/runtime failures (MacPorts itself,  
base/ sources), along with additions (enhancements) to our sources  
considered critical (I know this is rather vague, feel free to  
improve my suggestion);
	-) Blocker: still not too sure what we should use this for, probably  
something we should restrict to MacPorts project members' criteria on  
*really* important stuff in my opinion, more than plain "Important"  
above;
	-) Nice to have: port requests (either a request to write a portfile  
for a particular software package or a portfile submission for said  
package) and "less than critical" additions to MacPorts sources  
(again rather vague, I know);
	-) Not set: anything else that doesn't fit in the above set;
	-) do we need any other priority? feel free to suggest them, I can  
create whichever we might need;

  *) Component: Currently listed in the existing doc, but limited to  
"ports" and "base"; those two are keepers, but:
	-) we should include "guide" and "www" (I do hope one day we'll re- 
design our entire web page!);
	-) "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;
	-) "infrastructure": should be reserved for MacPorts team members,  
since they're likely to have a better feel for the infrastructure  
requirements we have, which we don't and which are already in the  
works (we don't want to waste macosforge admin personnel's time ;-)

  *) Severity: there will probably be some discrepancy here, as  
determining what's of mild severity, serious or critical is not  
likely to be an incredibly objective decision. In any case, my thoughts:
	-) Normal: what most reports should list (my problems are mine, not  
the entire world's ;-), like regular port build failures,  
documentation typos, etc;
	-) Serious: Should we reserve this exclusively for MacPorts build/ 
runtime failures...? (why would one port build failure be more  
important than another? they shouldn't be listed here);
	-) Security: tickets with update requests (with or without patches)  
that address security concerns in any given port and/or MacPorts itself?
	-) Performance: Improving MacPorts performance?
	-) Crash/data loss: this sounds unnecessarily alarmist to me, maybe  
we should get rid of it and put tickets here under "Serious"...?
	-) Other: whatever doesn't fit in the above set (just the same as  
priorities, feel free to suggest any other severity level you think  
we might need).

  *) Assign to: just fine as it is now;

  *) 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:
	-) Documenation: self explanatory (noting that reports against  
things like our man pages, though in the documentation milestone,  
should be filed under the "base" component, not "guide");
	-) Feature requests: for something MacPorts is missing, with or  
without a patch implementing it ("base" component);
	-) MacPorts x.y: tickets against MacPorts itself that have been  
accepted for fixing/inclusion in whatever iteration of the currently  
shipping MacPorts base version (like all tickets that were fixed in  
every single 1.4.x release belonged in the 1.4 milestone, not in  
1.4.x specific milestones --which rapidly becomes hard to manage--);  
note that tickets in these milestones should be under the "base"  
component, with some exceptions for the "ports" component that make  
sense in a particular MacPorts release, like ticket #11664;
	-) Needs developer review: those tickets against MacPorts sources  
that are still lacking consensus and need discussion to make it into  
a particular release milestone; note that tickets that are agreed  
upon but don't have any man power to implement them yet (i.e. create  
a patch) should really be in "Feature Requests", not here nor in a  
version specific milestone;
	-) New Ports: tickets requesting the introduction of a new port into  
our tree, with an attached Portfile;
	-) Port Bugs: tickets reporting/fixing a port specific build or  
runtime failure;
	-) Port Enhancements: tickets that simply enhance an already working  
port in whatever way;
	-) Port Requests: tickets kindly asking that someone embarks on the  
task of writing a Portfile for the requested packages (that is, those  
requests that aren't exactly "New Ports" because they don't come with  
a Portfile attached);
	-) Port Updates: tickets upgrading a port to a new version (a very  
particular type of "port enhancement" that committers like to fine- 
grain);

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

  *) Keywords: Advice everyone to put in here whatever they think  
might help us find their tickets quicker (like the portname, "build  
failure", "runtime failure", "misconfiguration", whatever);

  *) Cc: fine as it is now, but lets get rid of the probably  
unnecessary "(Trac is capable of sending such emails, but this is  
currently disabled on the MacPorts server, and unfortunately we  
neither maintain the server, nor have yet been able to persuade the  
actual maintainers to change this.)" comment; as we say here in my  
country, dirty clothes are washed indoors ;-). Lets just say "that  
the server is not configured for that functionality at the moment"  
and I'll work a fix for this with Kevin Van Vechten. This  
misconfiguration is actually more something that has fallen through  
the cracks as we've moved on than a reluctance to change on his side;

  *) Attachments: just fine as it is now.


	Wow, now that was large! It took me a while to put together all the  
information and ideas I had in my head and write all that, so I hope  
it makes sense. Feel free to poll me on anything that sounds like  
crack smoking ;-)

	I'd like to make it clear what most of what's written above is  
either the existing implicit consensus and/or my very own ideas.  
Anyone reading should feel free to contradict me or otherwise argue  
with me for better guidelines. In any case, I believe it's most  
important that we take this out of "implicit" land and make it as  
explicit and available to users as possible. 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.

	So, I've already written enough and fear many gave up somewhere  
along the way. Gonna hit send without any further ado and will carry  
on in replies to questions if need be.

	Regards,...


-jmpp