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
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
On Jul 14, 2007, at 18:58, Chris Pickel wrote:
-) 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 also found the "priorities" in the MacPorts Trac to be rather odd. Colloquy's sounds better, but I'd even cut it down to just 3: high, normal and low. (How would you decide whether a bug is "high" or "highest" priority?)
*) 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?)
"Port Additions" sound like additions to an existing port. How about "Port Submissions" instead?
So I've got the draft of the new guide into a doctype "book" and chapters that are xincluded, but I can't get the Makefile in doc/guide to process it the way I want it. One issue is that I used <section> and the old guide uses <sect1>. Not sure which is preferred or if that is the problem. Should I check-in my new xml and see if someone else can look at the regen formatting problems? If so, can someone suggest new directory names to coexist with the old doc? The structure of the doc is like this, with each include a chapter. <book> <title>MacPorts Guide</title> <xi:include href="intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="installing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="using.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="portfiledev.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="portfileref.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="internals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="project.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </book> Mark
markd@macports.org writes:
So I've got the draft of the new guide into a doctype "book" and chapters that are xincluded, but I can't get the Makefile in doc/guide to process it the way I want it. One issue is that I used <section> and the old guide uses <sect1>. Not sure which is preferred or if that is the problem. Should I check-in my new xml and see if someone else can look at the regen formatting problems? If so, can someone suggest new directory names to coexist with the old doc?
Okay, I've got the Makefile tweaked after all for the Makefile "new" target. It works now. So now I just need suggestions for where to commit the new stylesheet and the xml chunks. Then it can be regened and hacked upon. Mark
On Jul 19, 2007, at 4:37 AM, markd@macports.org wrote:
markd@macports.org writes:
So I've got the draft of the new guide into a doctype "book" and chapters that are xincluded, but I can't get the Makefile in doc/guide to process it the way I want it. One issue is that I used <section> and the old guide uses <sect1>. Not sure which is preferred or if that is the problem. Should I check-in my new xml and see if someone else can look at the regen formatting problems? If so, can someone suggest new directory names to coexist with the old doc?
Okay, I've got the Makefile tweaked after all for the Makefile "new" target. It works now. So now I just need suggestions for where to commit the new stylesheet and the xml chunks. Then it can be regened and hacked upon.
Mark
Hey Mark! Great to hear you've advanced so much, really eager to take a detailed look at your work! Sorry for not having participated too much lately, I've been really short of time. But I will get to it first thing as soon as I have some spare time. Getting your work committed in the mean time will surely help many beat me to it ;-) So, about committing, off the top of my head I'd suggest the following: trunk/doc/guide trunk/doc/guide/new trunk/doc/guide/new/resources trunk/doc/guide/new/xml Just as the existing one, resources for the css and xml for the source files. We'd have to adapt the Makefile targets to find the new file but once we are good to replace old with new the move will be pretty simple. That's just off the top of my head though, feel free to improve on the suggestion as you lay the source files down. Thanks again for the effort and the hard work, most appreciated! (by me and all users, I'm sure ;-) Regards,... -jmpp
On Jul 19, 2007, at 4:37 AM, markd@macports.org wrote:
Okay, I've got the Makefile tweaked after all for the Makefile "new" target. It works now. So now I just need suggestions for where to commit the new stylesheet and the xml chunks. Then it can be regened and hacked upon.
The new guide is now also automatically regenerated once a day and is available at: http://geeklair.net/new_macports_guide/ enjoy :) -- Daniel J. Luke +========================================================+ | *---------------- dluke@geeklair.net ----------------* | | *-------------- http://www.geeklair.net -------------* | +========================================================+ | Opinions expressed are mine and do not necessarily | | reflect the opinions of my employer. | +========================================================+
On Jul 19, 2007, at 4:18 PM, Daniel J. Luke wrote:
On Jul 19, 2007, at 4:37 AM, markd@macports.org wrote:
Okay, I've got the Makefile tweaked after all for the Makefile "new" target. It works now. So now I just need suggestions for where to commit the new stylesheet and the xml chunks. Then it can be regened and hacked upon.
The new guide is now also automatically regenerated once a day and is available at:
http://geeklair.net/new_macports_guide/
enjoy :) -- Daniel J. Luke
Big woot! Thanks Daniel! -jmpp
Hi everyone,
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? ;-)
Just letting you know that I'm still here, but haven't got to this thread yet after a few days out of things. The answer is "I don't mind at all", and I'll get back to you with more as soon as I can! Kind regards, Maun Suang -- Boey Maun Suang (Boey is my surname) Email: boeyms at macports dot org
On Jul 20, 2007, at 1:27 AM, Boey Maun Suang wrote:
Hi everyone,
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? ;-)
Just letting you know that I'm still here, but haven't got to this thread yet after a few days out of things. The answer is "I don't mind at all", and I'll get back to you with more as soon as I can!
Kind regards,
Maun Suang
Thanks for accepting the task, Maun Suang! I just finished compiling the consensus we've reached so far on the new guidelines into the following document: http://trac.macports.org/projects/macports/wiki/NewTracTicketing Please note that what's written there is an overall rough explanation of what our recommendations should look like moving forward, recommendations themselves still need to be formally written into the guide (/me summons the documentation kings!). Also note that I wrote a "Pending" section in which I detail both what we need to look into and the aspects of the new guidelines that are still up in the air in discussion. I compiled all that from the feedback I got on this thread last week. Please post to this list with your comments before editing that document (meant to anyone reading). Lastly, it is my intention to delete the NewTracTicketing wiki entry once the new guidelines are fully in place in the new guide, and turning the existing TracTicketing wiki entry into a redirect to the appropriate section in the guide. Hope I didn't miss anything, feel free to yell at me ;-) Regards,... -jmpp
Juan Manuel Palacios <jmpp@macports.org> writes:
http://trac.macports.org/projects/macports/wiki/NewTracTicketing
I just committed a try at the Trac guidelines in the new guide. See what you think and modify. I also threw in a screenshot in that section. If it seems unnecessary or not helpful it could be yanked. Also, can we describe better the difference between "component" and "milestone". The overlap is confusing. Or could these two be combined in some way? Mark
On Jul 27, 2007, at 2:42 AM, markd@macports.org wrote:
Juan Manuel Palacios <jmpp@macports.org> writes:
http://trac.macports.org/projects/macports/wiki/NewTracTicketing
I just committed a try at the Trac guidelines in the new guide. See what you think and modify. I also threw in a screenshot in that section. If it seems unnecessary or not helpful it could be yanked.
Thanks for embarking on this Mark, great work! And also nice going with the picture, I think it looks great in there! Going forward I would love to see the TracTicketing document be turned into a redirect to these new guidelines and also somehow link them off the http://trac.macports.org/projects/macports/newticket page through some kind of banner at top right corner.I'll talk to Kvv about that. We can also delete my NewTicketingGuidelines document, but I would like to first finish all the pending items before doing so.
Also, can we describe better the difference between "component" and "milestone". The overlap is confusing. Or could these two be combined in some way?
I'll see how the descriptions can be improved, but I'd very much prefer either keeping them separate or on the other hand safeguarding the milestones as much as possible, since they are what feeds the roadmap. On the topic of correcting documentation, I uploaded two patches to the corresponding milestone and will shortly provide a couple more, have a look if you may ;-)
Mark
Regards,... -jmpp
participants (6)
-
Boey Maun Suang
-
Chris Pickel
-
Daniel J. Luke
-
Juan Manuel Palacios
-
markd＠macports.org
-
Ryan Schmidt