[gentoo-commits] proj/elections:master commit in: /

[Robin H. Johnson]

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.