Merge d493fe6 into 158b05f

MANIFEST

@@ -5422,6 +5422,7 @@ Porting/timecheck.c		Test program for the 2038 fix
 Porting/timecheck2.c		Test program for the 2038 fix
 Porting/todo.pod		Perl things to do
 Porting/valgrindpp.pl		Summarize valgrind reports
+Porting/vote_admin_guide.pod	Perlgov Vote Administrator guide
 pp.c				Push/Pop code
 pp.h				Push/Pop code defs
 pp_ctl.c			Push/Pop code for control flow

Porting/README.pod

@@ -379,5 +379,9 @@ collects all these files, extracts most of the information and produces a
 significantly shorter summary of all detected memory access errors and memory
 leaks.
 
+=head2 F<vote_admin_guide.pod>
+
+Guide for Vote Administrators for running Steering Council elections.
+
 =cut
 

Porting/vote_admin_guide.pod

@@ -0,0 +1,176 @@
+=encoding utf8
+
+=head1 NAME
+
+vote_admin_guide - Perl Governance Vote Administrator Guide
+
+=head1 Running a Steering Council nomination process
+
+Announce the nomination period to the Perl Core mailing list.  Be explicit
+about the end time.  Set a calendar reminder for yourself for when it's
+time to close the nominations and begin the voting.
+
+If someone outside the Core Team is nominated, contact them to confirm that
+they accept the nomination.  If they do, ask the Steering Council to add
+them as a moderated member of the Perl Core list for the duration of the
+election and invite them to offer a statement on their candidacy to the
+list.
+
+Remind inactive Core Team members that they have until the end of
+nominations to reactivate themselves if they wish to vote.
+
+Before the end of the nomination period, remind everyone of the schedule
+and share the current list of nominees to confirm you aren't missing
+anyone.
+
+At the end of the nomination period, notify the Perl Core list of the list
+of nominees and set their expectations for when you'll be opening the
+voting period.
+
+=head1 Using CIVS
+
+We are using L<Condorcet Internet Voting Service|https://civs.cs.cornell.edu/>
+(CIVS), which is pretty easy to use, although it has a lot of options.
+
+First, bookmark that link, but realize that there are no user accounts.
+Whenever you create or participate in a poll, you'll get a unique URL, and you
+need to save it to come back to what you were doing before.
+
+=head2 Preliminary work
+
+You'll need to complete these steps.
+
+=head3 Get list of active Core Team member emails
+
+Ask Rik Signes for an up-to-date list of active Core Team member emails from
+the TopicBox mailing list.
+
+B<TODO>: Replace this step with a machine-readable list of email addresses in
+C<Porting>.
+
+=head3 Remind Core Team members to opt-in their email address
+
+CIVS has a required opt-in to send polls out to an email address. The
+active Core Team members that would like to vote and haven't opted-in yet
+must use the following link with the email address they use for the
+perl-core mailing list: L<https://civs1.civs.us/cgi-bin/opt_in.pl>
+
+=head2 Running an election on CIVS
+
+The following instructions describe steps to run an election.
+
+=head3 Creating a poll
+
+On the right sidebar of the CIVS landing page is a list of links, and the
+first one is Create a poll.  Some of the things it asks for are simple:
+what's it called?  Who is running it?  It asks for an email address, and it
+has to work: that's where you're going to get all the links!
+
+Note that "day and time you plan to stop" is just a text box.  It gets sent
+to the recipient in their invitation to vote.  It does not schedule one
+dang thing, so you better set yourself a reminder to close the poll on
+time!  Also, remember to think about time zones!  (You are free to
+selfishly pick your local time.)
+
+The description box is limited HTML: you can put in C<< <p> >> and
+C<< <b> >> and C<< <ul> >> and C<< <a> >> and some other basics.  Hit
+"preview" whenever you want.  Also, you'll be able to see the email
+before you send it to everybody.
+
+The "names of choices" is line by line.  Blanks are ignored.  Again, use
+preview.  Also, note that these will be presented to the voters in random
+order, so the order you put the candidates doesn't matter.  (CIVS lets you
+force the ordering, but we don't use that.)
+
+The options you want are:
+
+    * How many choices will win: 3
+    * Private
+    * Enable detailed ballot reporting: true
+    * Enforce proportional representation: true
+        Assume maximizing rank of their favorite choice: true
+
+Leave all other options off.
+
+Then you can create the poll.
+
+=head3 Start the poll
+
+You'll get an email linking back to the poll's control page.
+
+B<BOOKMARK THE CONTROL PAGE!>
+
+Don't lose that link or you won't be able to administer the poll and you'll
+have to re-create it.
+
+From here, you can double check your settings.  Some things, but not all,
+can be edited.
+
+If it looks good, click "start poll."  You'll get a success page and can
+click "go back to poll control".
+
+=head3 Check how the email looks
+
+At the bottom, under "Add voters", enter your email address.  Click "add
+voters."  You'll get another success screen and can again "go back to poll
+control."
+
+Meanwhile, you'll get another email, this one linking you to the voting
+page itself.  Proofread the email.  Click the link. Proofread the page.  If
+you want, cast your vote!
+
+At this point, you probably either need to start over - because you can't
+edit a poll once it's going - or you're good to proceed.   If you need to
+start over, just close the poll (or not, but it seems polite to do so) and
+start over.  Otherwise...
+
+=head3 Send the poll!
+
+This is the point of no return!  Once you send the poll to the whole team,
+you'll look silly if you made a big mistake.  That's okay, you can survive
+looking silly, but it's better to avoid it if you can.
+
+Put all the email addresses for the team into the "add voters" on the poll
+control page.  There should be as many of these as there are team members.
+Double check!  It's okay if you enter your email address, again.  You won't
+be allowed to vote twice.
+
+Click "add voters."  It will take a little while.  (I think it does all the
+email sending synchronously.)  When that's done, you can email the list to
+say the ballot has been sent.
+
+If you're told that some email addresses aren't authorized to vote, chase
+down these Core Team members that haven't opted-in their email address.
+
+=head3 Wait
+
+Now you just need to wait for the end date.  Set a calendar alarm to remind
+yourself.  Look at the poll control page once in a while to see how many votes
+were cast.  Because votes can't be edited once cast, you could end the voting
+immediately once 100% of ballots have been cast, but don't expect this will
+actually happen.
+
+=head3 End the poll
+
+When it's time, go to the poll control page and click "end poll".  You'll get
+dumped on a results page that will provide the three winners (and a bunch of
+other data).  Use the "minimax" rule (the default).  Everyone else will be able
+to access these results, so don't worry about copying anything but the winners.
+Inform the group!
+
+=head2 After an election
+
+In addition to notifying the Perl Core mailing list of the results, open a
+pull request to update perlgov.pod with the new Steering Council members.
+If a non-Core-Team candidate won, also add them to the Core Team list.
+
+Ask the outgoing Steering Council to change the Perl Core mailing list
+administrators to match the incoming Steering Council.
+
+Update this guide with any clarifications or new information that will help
+the next Vote Administrator.
+
+Relax and congratulate yourself!
+
+=cut
+