Extension: Add initial documentation.

etc/OneTicketPerRequestor.yml

@@ -0,0 +1,7 @@
+---
+# Keys are queue names.
+# Values are either a string, or an array of strings, with
+# TicketSQL ordering like "Created DESC" or "id ASC".
+# For each queue in this file, the OneTicketPerRequestor mail plug-in
+# will redirect incoming mail to the first ticket from the requestor
+# that matches with the ordering you specified.

lib/RT/Extension/Conservancy.pm

@@ -1,12 +1,86 @@
-# This extension is free software.
-# You may distribute it under the terms of the GNU General Public License,
-# version 3.0, or (at your option) any later version published by the
-# Free Software Foundation.
-
 use strict;
 use warnings;
 package RT::Extension::Conservancy;
 
 our $VERSION = '0.2';
 
+=pod
+
+=head1 RT::Extension::Conservancy
+
+A collection of RT extensions developed for Software Freedom Conservancy.
+
+=head2 Contents
+
+=head3 RT::Action::NotifyOwnerOrQueueAdminCcs
+
+A Scrip action that sends notice to the ticket owner if that's set, or queue
+AdminCCs if not.  Ticket AdminCCs always get the notice too, which is how
+this is different from the built-in "Notify Owner or AdminCCs".
+
+=head3 RT::Interface::Email::OneTicketPerRequestor
+
+A mail plugin that examines incoming mail to see if it would create a new
+ticket.  If so, and the requestor already has a ticket in the destination
+queue, the mail is turned into correspondence on the existing ticket
+instead.
+
+You can configure which queues this works for, and what ticket the mail gets
+merged into (in case there's more than one from ticket history, or admins
+creating multiple through the web interface, etc.).  Edit
+C<etc/OneTicketPerRequestor.yml> following the instructions in the comments.
+
+=head2 Requirements
+
+Works with RT 4.4.
+
+=head2 Installation
+
+=over 4
+
+=item Check out this repository in your RT plugins directory.
+
+=item Edit your RT site configuration to include the line
+C<Plugin("RT-Extension-Conservancy")>.
+
+=item If you want to use the OneTicketPerRequestor mail plugin, make sure
+your site configuration sets C<@MailPlugins>, and the list includes
+C<"OneTicketPerRequestor">.
+
+=item Run in a shell from your checkout:
+C<for f in etc/upgrade/*/content; do rt-setup-database --insert --datafile "$(realpath -s "$f")" || break; done>
+
+=item Restart your RT server.
+
+=back
+
+=head2 Upgrading
+
+=over 4
+
+=item Before you upgrade anything, note the C<$VERSION> of this extension
+you're currently running.
+
+=item Update your plugin checkout to the version you want with C<git pull>,
+C<git checkout>, etc.
+
+=item Repeat the C<rt-setup-database> step from the Installation step,
+running it only on the versions that are later than the C<$VERSION> you
+noted two steps ago.
+
+=item Restart your RT server.
+
+=back
+
+=head2 Copyright and License
+
+Copyright © 2018 Brett Smith <brettcsmith@brettcsmith.org>
+
+This extension is free software.
+You may distribute it under the terms of the GNU General Public License,
+version 3.0, or (at your option) any later version published by the
+Free Software Foundation.
+
+=cut
+
 1;