commit: 533bedb17bdf5ad652cca631574537d356a5901a
Author: Robin H. Johnson <robbat2 <AT> gentoo <DOT> org>
AuthorDate: Sat Jun 20 05:11:15 2020 +0000
Commit: Robin H. Johnson <robbat2 <AT> gentoo <DOT> org>
CommitDate: Sat Jun 20 05:11:15 2020 +0000
URL: https://gitweb.gentoo.org/proj/elections.git/commit/?id=533bedb1
README: braindump of the entire election process
Signed-off-by: Robin H. Johnson <robbat2 <AT> gentoo.org>
README | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 91 insertions(+)
diff --git a/README b/README
index 7dee785..45490f5 100644
--- a/README
+++ b/README
@@ -21,3 +21,94 @@ listify: generate text to include in MOTD
election-stats-count: generate turnout stats for ongoing elections, for
election officials to review an election in progress (put it in a cronjob,
needs root).
+
+Instructions
+------------
+1. Setup an election:
+---------------------
+To create a new election, make a top-level directory with the exact name of
+the election. Usually in the format of `{council,trustees}-YYYYMM`.
+Let ${election_name} be the name of the election. Any member of the elections
+project or infra may set this up.
+
+- `Votify.pm`: symlink to ../Votify.pm for tooling
+- `ballot-${election_name}`
+ One entry per line, in alphabetical order.
+ The special candidate `_reopen_nominations` is valid in some elections.
+ The ballot order will be randomized per candidate, at voting time.
+- `election-details`:
+ key-value file with details about the election.
+ `name`: exact election name
+ `startDate`, `endDate`: start & end time in UTC
+ `officials`: election officials (prohibited from being candidates)
+ `voters`: URL to list of members who may cast a ballot
+ `ballot`: URL to sample ballot
+- `officials-${election_name}`: list of election officials
+- `start-${election_name}`: election start time, as epoch seconds.
+- `stop-${election_name}`: election end time, as epoch seconds.
+- `voters-${election_name}`: list of members who may cast a ballot
+
+Populate the files, commit & push to Git. At the start time, an official
+should verify that the ballot works. Ideally a non-infra official, who then
+confirms to the infra election handler it worked.
+
+2.1. Let people vote:
+-------------------
+The regular way is to login to `dev.gentoo.org` and run `votify`.
+
+2.2. Handle special ballots:
+--------------------------
+Some elections may have voters who cast ballots by irregular means: they
+should be accepted only via GPG-signed email to the election officials, who
+should agree that the signature is valid and matches a key that was already on
+a list prior to the election. The infra contact should place the ballot in
+`dev.gentoo.org:/home/$membername/.ballot-${election_name}-submitted`
+
+The elections mechanisms make no provision for truely secret ballot: election
+officials WILL see the content of the ballot.
+
+This is primarily a requirement for the Trustees election, which accepts
+ballots from all Foundation members. The roll of Foundation members includes
+active developers, retired developers, and other applicants to the Foundation
+Trustees.
+
+3. Wait:
+--------
+Just wait. `election-stats-count` runs every 30 minutes by cronjob, and prints
+status files into the home directories of election officials:
`voter-turnout-${election_name}`.
+
+4. Close of election:
+---------------------
+This is where the infra contact is absolutely required.
+The infra contact must run `countify --collect` as root, which will write
+the master ballot & confirmation stub file to all officials.
+
+5. Verify results:
+------------------
+Each election official should verify the results to collectively certify the
+results. This requires `countify --rank` to transform the master ballot into
+results.
+
+6. Email conf stubs:
+--------------------
+ONE election official should use the mail-voters scripts to send confirmation
+stubs to each eligable voter. Note that this is ALL eligable voters, and not
+just those that cast a ballot.
+
+7. Announce results:
+--------------------
+The collected election officials should announce results; The email should
+include the output of `countify --rank`, as well as the master ballot for
+independent verification.
+
+8. Cleanup:
+-----------
+- The master ballot must be committed to git. This file is named
+ `master-${election_name}`
+- This list of voters who cast a ballot should be recorded & committed.
+ This is required to purge rolls of inactive voters in some cases (Foundation
+ members are required to vote at least every 2nd election if they are not an
+ active developer). This file must be named `casting-voters-${election_name}`
+- The confirmation stub file should be destroyed after the election results
+ have been formally accepted, to make de-anonymizing the ballots harder.
+- Lastly, `git mv` the election directory into the `completed/` directory.
