From 247f865bf13016731beed5e2254c2528f971c763 Mon Sep 17 00:00:00 2001 From: "Robin H. Johnson" Date: Thu, 17 Jun 2021 23:55:14 -0700 Subject: README.md: refresh docs Signed-off-by: Robin H. Johnson --- README.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..a59ed18 --- /dev/null +++ b/README.md @@ -0,0 +1,144 @@ +Gentoo Elections +---------------- + +Welcome to the Gentoo Elections codebase. + +This handles all elections per the [Gentoo Elections](https://wiki.gentoo.org/wiki/Project:Elections) project. + +The Condercet system is used, and most of this repository exists just to house +the actual data needed to run each election, such as the start/stop time, +eligable voters, blank ballot etc. + +Completed elections are available in the `completed/` directory. + +The codebase is meant to be checked out somewhere read-only (Gentoo +Infrastructure uses `/etc/elections/`), with the `votify` & `countify` scripts +symlinked into somewhere used by $PATH for normal users (eg `/usr/local/bin`). + +`listify` & `election-stats-count` are other helpful tools. + +- `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. + +The URLs may link to either of two repos for the data: +- `sites/projects/elections.git`, which populates: + `https://projects.gentoo.org/elections/TYPE/YYYY/...` +- `projects/elections.git` (this repo), which is only visible on Gitweb: + https://gitweb.gentoo.org/proj/elections.git/ + +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 the only step where the infra contact is absolutely required. +The infra contact must run `countify --collect ${election_name}` as root, +which will write the master ballot & confirmation stub file to all officials: +``` +$ sudo su +# cd /etc/elections +# ./countify --collect ${election_name} +# find /home/${official}/results-${election_name}/ +/home/${official}/results-${election_name}/master-${election_name} +/home/${official}/results-${election_name}/confs-${election_name} +``` + +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. +``` +$ cd /home/${official}/results-${election_name} +$ countify --rank | tee ranked-${election_name} +(election output) +``` + +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 following files must be commited to `proj/elections.git` repo. + - `master-${election_name}` + - `casting-voters-${election_name}` + - `ranked-${election_name}` +- The some files should also be copied with renames into the + `sites/projects/elections.git` repo as follows: + - `ballot-${election_name}` -> `ballot-${election_name}.txt` + - `master-${election_name}` -> `master-${election_name}.txt` + - `ranked-${election_name}` -> `${election_name}-results.txt` + - `voters-${election_name}.txt` -> `voters-${election_name}.txt` +- `casting-voters-${election_name}` is a list of voters who cast a ballot, and + needs to be recorded. 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). +- The confirmation stub file `confs-${election_name}` MUST 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. -- cgit v1.2.3-65-gdbad