# Copyright (C) 2001-2006, The Perl Foundation.
# $Id: wranglers.pod 17085 2007-02-20 20:04:14Z paultcochrane $

=pod

=head1 NAME

docs/dev/wranglers.pod - Tips for Ticket Wranglers

=head1 ABSTRACT

This document attempts to outline a set of "best practices" for dealing with
tickets in Parrot's RT system.  It is targeted at Parrot developers and "Ticket
Wranglers" and is I<not> intended as advice or instruction for end users.  Ticket
filing procedures for end users are documented in F<docs/submissions.pod>.

=head1 WHAT IS A TICKET WRANGLER?

A developer with sufficient permissions to modify the tickets in Parrot's RT
system.  All Parrot developers are expected to pitch in and help keep the ticket
tracker in a healthy state.  I<This means you!>

=head1 WHERE IS IT?

The Parrot ticket tracker is currently the same as the I<Perlbug> system used for
Perl5 Development.  It is available at L<https://rt.perl.org>.
The Parrot issues are in the queue I<parrot>.

=head1 TICKET HANDLING PROCEDURES

=head2 New Tickets

Where I<New> refers to a pre-existing ticket sitting in the Parrot queue with a
status of C<new>.

=head3 Bug Triage

Involves deciding whether the ticket is a real bug, a feature request, a
duplicate or spam.

It is especially important that all C<new> bugs which are marked [TODO],
[PATCH] or [CAGE] be checked that they really are bugs of the given class.
This is because some bugs, such as [TODO] and [CAGE] get their status set to
C<open> to indicate that something should be done, rather than something is
being done.

=over 4

=item Is this spam?

Assign the issue to the queue I<spam>. Note that if this is successful, you
will no longer have permissions to view the ticket.

=item Is this a duplication of an existing ticket?

RT doesn't handle that case in a graceful manner. Set the relationship
'dependent on' to the duplicate issue. Add a comment to the ticket along the
lines of "Duplicate of Ticket #123" and change the Tag field to "duplicate".
Also, change the status to "rejected".

=item Is there enough information?

If not, ask for more input.

=item Is it a [TODO] ticket?

Is the subject line in the format C<"[TODO] subsystem - issue>?

C<[TODO]> tickets should have their status changed to C<open> to prevent them
from appearing in a listing of C<new> tickets.

=item Is it a [PATCH] ticket?

Is the subject line in the format C<"[PATCH] subsystem - issue>?

Make sure that there is actually a patch attached to the ticket. If you've
applied a patch, be sure to include the revision in your response when closing
the ticket.

=item * Is it a [CAGE] bug?

Is the subject line in the format C<"[CAGE] subsystem - issue>?

C<[CAGE]> bugs should have their status changed to C<open> to prevent them from
appearing in a listing of C<new> bugs.

=item * Assign the bug to someone if at all possible.

=back

=head2 TODO Tickets

=over 4

=item Claim ownership or interest ( CC ) of the ticket.

This way you will receive further correspondence about the ticket.

=item Run the test suite

=item make manitest

=item add the patch author to CREDITS or update the author's entry

=item add correspondence to the ticket stating that the patch was applied
and include the svn revision number in your response.

=item make sure that the ticket's 'Tag' includes 'Patch'

=item set the ticket's 'Patch Status' to 'Applied'

=item set the ticket's 'Status' to 'resolved'

=back

=head2 Old Tickets

If the ticket is more then I<1 month> old then it's considered I<old>.

=over 4

=item Ping the requestor

Give the requestor at least I<1 week> to respond.  If no response is received
then add a comment to the ticket saying that it is stalled because of no
response from the requestor. Change the status to C<stalled>.

If it's a [PATCH] ticket, it's possible that the patch was applied but the
ticket/patch status was never changed.   Also, not all list traffic regarding a
ticket ends up in RT.  It's best to look at the SVN repo to attempt to
determine if the ticket was resolved.

=item Review of stalled tickets

Sometimes tickets are marked C<stalled> because there's no hope if fixing them
soon. Sometimes, no response is available from the requestor, or it can't be
verified. Periodically, these tickets should be reviewed, and when possible,
moved back to C<open> or C<closed>, as appropriate.

=back

=head1 TIPS FOR CORRESPONDENCE

=head2 Don't be a Butthead

Remember that every word you type into the ticket tracker is I<On The Record>.
Try not to say anything that could offend or hurt the feelings of I<anyone>.
That includes the ticket submitter and other developers.  When, as a Parrot
developer with commit rights, you send correspondence you are representing the
Parrot project and by proxy TPF.  If in doubt, either send the message
privately or not at all.

=head2 Say thank you!

Try to add a little token of appreciation to every message you send in response
to a ticket.  Ticket requestors are doing labor for free!  The least you can do is
let them know that you appreciate their efforts.

Something like:

    Thanks,

    Thanks for following up.

    Thanks for reporting.

    Thanks for X!

Can work wonders.  If you can make someone feel good about themselves maybe
they'll submit another ticket/patch/whatever or perhaps some day become a
Parrot developer.

=head2 Don't say "problem"

Supposedly it's better customer relations to use I<issue(s)> instead of the
I<problem(s)>.  Don't ask me why...

=head2 Make it clear why the ticket status changed

Always note why the ticket is having it's status changed.  Particularly if it
is being closed or rejected.  Nothing will irritate people more then letting
them think that their ticket was unimportant or ignored.

=head2 Example Correspondence

    Hi,

    Can you retest for this ticket with the latest sources from SVN and confirm
    that this still an open issue?

    Thanks,

    -J

or

    Hi,

    Would you mind retesting with the latest sources from SVN?

    Thanks,

    -J

or

    Hi,

    Can you resubmit this patch different against SVN trunk?

    Thanks,

    -J

or

    Patch applied as rXXX.  Thanks for submitting.

    -J

or

    No response for requestor.  Ticket being marked as 'rejected'.
    Thanks for reporting.

    -J

or

    This doesn't appear to be an issue anymore.
    Thanks for submitting

    -J

or

    Marking this ticket as 'resolved' because it seems to have fixed itself.
    Thanks for following up.

    -J

=head1 SVN USAGE TIPS

=head2 Commit messages

=over 4

=item Put a subsystem identifier out the front

  [tcl]: commit message

=item If related to an RT ticket, use the ticket title

  [tcl]: #37301: [BUG] 9262: env tests failing on win32

=item Add a "Courtesy of <foo>" if supplied by someone else

  Courtesy of A. U. Thor <author@cpan.org>

=item Detailed commit messages are preferred

Make it clear what your intent is when committing. It makes future maintenance
much easier.

  [PGE]:
  * Switched "PGE::Regex" to be "PGE::Grammar", to be more accurate.
  * Moved default rules from PGE::Regex into PGE::Match.
  * Updated various languages and tools to match.

=item Commit file names

You don't need to include the filename in the commit message as that's part
of the commit itself. However, if your commit affects multiple directories,
you may mention that, especially if it's part of a group of commits.

  [PDD07]: whitespace -- part 5
  ~ removed trailing spaces and tabs from t/exit/, t/dynpmc/, t/dynoplibs/

=item Group similar commits by parts

If all commits are much the same and require basically the same commit
message, it can be useful to number the commit messages. For example:

  [tools]: smartlink functionality -- part 3
  ~ added regex attribute to Keyphrase class
  ~ filled in some more SmartLinkServer attribute init code
  ~ expanded LinkTree class functionality
  still TODO: merge smartlink and spec info, emit html, improve cmdline option code

You may optionally include items that are still todo, as it helps make your
intentions clear.

=item More ideas

Look at past commit messages, and L<http://cia.navi.cx/stats/project/parrot>
for more best practices.

=back

=head1 AUTHOR

Joshua Hoblitt (JHOBLITT) C<jhoblitt@cpan.org>

=cut

