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