Porting/vote_admin_guide.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 vote_admin_guide - Perl Governance Vote Administrator Guide
   6
   7 =head1 Running a Steering Council nomination process
   8
   9 Announce the nomination period to the Perl Core mailing list.  Be explicit
  10 about the end time.  Set a calendar reminder for yourself for when it's
  11 time to close the nominations and begin the voting.
  12
  13 Remember that inactive Core Team members may not participate in the nomination
  14 or voting process.  The governance document is clear that inactive members may
  15 not declare themselves active when a vote is proposed, which includes the
  16 nomination process.
  17
  18 If someone outside the Core Team is nominated, contact them to confirm that
  19 they accept the nomination.  If they do, ask the Steering Council to add
  20 them as a moderated member of the Perl Core list for the duration of the
  21 election and invite them to offer a statement on their candidacy to the
  22 list.
  23
  24 Before the end of the nomination period, remind everyone of the schedule
  25 and share the current list of nominees to confirm you aren't missing
  26 anyone.
  27
  28 At the end of the nomination period, notify the Perl Core list of the list
  29 of nominees and set their expectations for when you'll be opening the
  30 voting period.
  31
  32 =head1 Using CIVS
  33
  34 We are using L<Condorcet Internet Voting Service|https://civs.cs.cornell.edu/>
  35 (CIVS), which is pretty easy to use, although it has a lot of options.
  36
  37 First, bookmark that link, but realize that there are no user accounts.
  38 Whenever you create or participate in a poll, you'll get a unique URL, and you
  39 need to save it to come back to what you were doing before.
  40
  41 =head2 Preliminary work
  42
  43 You'll need to complete these steps.
  44
  45 =head3 Get list of active Core Team member emails
  46
  47 This can be found in the F<Porting/core-team.json> file.
  48
  49 =head3 Remind Core Team members to opt-in their email address
  50
  51 CIVS has a required opt-in to send polls out to an email address. The active
  52 Core Team members that would like to vote and haven't opted-in yet must use the
  53 following link with the email address they have in F<core-team.json>:
  54 L<https://civs1.civs.us/cgi-bin/opt_in.pl>
  55
  56 =head2 Running an election on CIVS
  57
  58 The following instructions describe steps to run an election.
  59
  60 =head3 Creating a poll
  61
  62 On the right sidebar of the CIVS landing page is a list of links, and the
  63 first one is Create a poll.  Some of the things it asks for are simple:
  64 what's it called?  Who is running it?  It asks for an email address, and it
  65 has to work: that's where you're going to get all the links!
  66
  67 Note that "day and time you plan to stop" is just a text box.  It gets sent
  68 to the recipient in their invitation to vote.  It does not schedule one
  69 dang thing, so you better set yourself a reminder to close the poll on
  70 time!  Also, remember to think about time zones!  (You are free to
  71 selfishly pick your local time.)
  72
  73 The description box is limited HTML: you can put in C<< <p> >> and
  74 C<< <b> >> and C<< <ul> >> and C<< <a> >> and some other basics.  Hit
  75 "preview" whenever you want.  Also, you'll be able to see the email
  76 before you send it to everybody.
  77
  78 The "names of choices" is line by line.  Blanks are ignored.  Again, use
  79 preview.  Also, note that these will be presented to the voters in random
  80 order, so the order you put the candidates doesn't matter.  (CIVS lets you
  81 force the ordering, but we don't use that.)
  82
  83 The options you want are:
  84
  85     * How many choices will win: 3
  86     * Private
  87     * Enable detailed ballot reporting: true
  88     * Enforce proportional representation: true
  89         Assume maximizing rank of their favorite choice: true
  90
  91 Leave all other options off.
  92
  93 Then you can create the poll.
  94
  95 =head3 Start the poll
  96
  97 You'll get an email linking back to the poll's control page.
  98
  99 B<BOOKMARK THE CONTROL PAGE!>
 100
 101 Don't lose that link or you won't be able to administer the poll and you'll
 102 have to re-create it.
 103
 104 From here, you can double check your settings.  Some things, but not all,
 105 can be edited.
 106
 107 If it looks good, click "start poll."  You'll get a success page and can
 108 click "go back to poll control".
 109
 110 =head3 Check how the email looks
 111
 112 At the bottom, under "Add voters", enter your email address.  Click "add
 113 voters."  You'll get another success screen and can again "go back to poll
 114 control."
 115
 116 Meanwhile, you'll get another email, this one linking you to the voting
 117 page itself.  Proofread the email.  Click the link. Proofread the page.  If
 118 you want, cast your vote!
 119
 120 At this point, you probably either need to start over - because you can't
 121 edit a poll once it's going - or you're good to proceed.   If you need to
 122 start over, just close the poll (or not, but it seems polite to do so) and
 123 start over.  Otherwise...
 124
 125 =head3 Send the poll!
 126
 127 This is the point of no return!  Once you send the poll to the whole team,
 128 you'll look silly if you made a big mistake.  That's okay, you can survive
 129 looking silly, but it's better to avoid it if you can.
 130
 131 Put all the email addresses for the team into the "add voters" on the poll
 132 control page.  There should be as many of these as there are team members.
 133 Double check!  It's okay if you enter your email address, again.  You won't
 134 be allowed to vote twice.
 135
 136 Click "add voters."  It will take a little while.  (I think it does all the
 137 email sending synchronously.)  When that's done, you can email the list to
 138 say the ballot has been sent.
 139
 140 If you're told that some email addresses aren't authorized to vote, chase
 141 down these Core Team members that haven't opted-in their email address.
 142
 143 =head3 Wait
 144
 145 Now you just need to wait for the end date.  Set a calendar alarm to remind
 146 yourself.  Look at the poll control page once in a while to see how many votes
 147 were cast.  Because votes can't be edited once cast, you could end the voting
 148 immediately once 100% of ballots have been cast, but don't expect this will
 149 actually happen.
 150
 151 =head3 End the poll
 152
 153 When it's time, go to the poll control page and click "end poll".  You'll get
 154 dumped on a results page that will provide the three winners (and a bunch of
 155 other data).  Use the "minimax" rule (the default).  Everyone else will be able
 156 to access these results, so don't worry about copying anything but the winners.
 157 Inform the group!
 158
 159 =head2 After an election
 160
 161 In addition to notifying the Perl Core mailing list of the results, open a
 162 pull request to update perlgov.pod with the new Steering Council members.
 163 If a non-Core-Team candidate won, also add them to the Core Team list.
 164
 165 Ask the outgoing Steering Council to:
 166
 167 =over
 168
 169 =item *
 170
 171 edit the Perl Core mailing list admins to match the incoming Steering Council
 172
 173 =item *
 174
 175 update the GitHub "steering" team to match incoming Steering Council
 176
 177 =item *
 178
 179 request that the Perl NOC update the perl-security list to include all incoming
 180 Steering Council members (without removing outgoing members; the incoming Steering
 181 Council will decide whether this is needed)
 182
 183 =back
 184
 185 Update this guide with any clarifications or new information that will help
 186 the next Vote Administrator.
 187
 188 Relax and congratulate yourself!
 189
 190 =cut
 191