commit: 247f865bf13016731beed5e2254c2528f971c763 Author: Robin H. Johnson <robbat2 <AT> gentoo <DOT> org> AuthorDate: Fri Jun 18 06:55:14 2021 +0000 Commit: Robin H. Johnson <robbat2 <AT> gentoo <DOT> org> CommitDate: Fri Jun 18 06:55:19 2021 +0000 URL: https://gitweb.gentoo.org/proj/elections.git/commit/?id=247f865b
README.md: refresh docs Signed-off-by: Robin H. Johnson <robbat2 <AT> gentoo.org> README => README.md | 61 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 22 deletions(-) diff --git a/README b/README.md similarity index 64% rename from README rename to README.md index 0d3c8e6..a59ed18 100644 --- a/README +++ b/README.md @@ -2,23 +2,24 @@ Gentoo Elections ---------------- Welcome to the Gentoo Elections codebase. -This handles all elections in Gentoo per the Elections project [1]. + +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. +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). +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` & `election-stats-count` are other helpful tools. -listify: generate text to include in MOTD +- `listify`: generate text to include in MOTD -election-stats-count: generate turnout stats for ongoing elections, for +- `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). @@ -28,14 +29,15 @@ Instructions --------------------- 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 + +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 +- `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. + 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 @@ -52,6 +54,12 @@ 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`. @@ -79,9 +87,9 @@ status files into the home directories of election officials: `voter-turnout-${e 4. Close of election: --------------------- -This is 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: +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 @@ -98,7 +106,7 @@ results. This requires `countify --rank` to transform the master ballot into results. ``` $ cd /home/${official}/results-${election_name} -$ countify --rank +$ countify --rank | tee ranked-${election_name} (election output) ``` @@ -116,12 +124,21 @@ 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. +- 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.
