From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id D963613835A for ; Fri, 18 Jun 2021 06:57:45 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 1A45CE0829; Fri, 18 Jun 2021 06:57:45 +0000 (UTC) Received: from smtp.gentoo.org (dev.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id EB51BE0829 for ; Fri, 18 Jun 2021 06:57:44 +0000 (UTC) Received: from oystercatcher.gentoo.org (unknown [IPv6:2a01:4f8:202:4333:225:90ff:fed9:fc84]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id E215533DE47 for ; Fri, 18 Jun 2021 06:57:43 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 90C827B2 for ; Fri, 18 Jun 2021 06:57:42 +0000 (UTC) From: "Robin H. Johnson" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Robin H. Johnson" Message-ID: <1623999319.247f865bf13016731beed5e2254c2528f971c763.robbat2@gentoo> Subject: [gentoo-commits] proj/elections:master commit in: / X-VCS-Repository: proj/elections X-VCS-Files: README README.md X-VCS-Directories: / X-VCS-Committer: robbat2 X-VCS-Committer-Name: Robin H. Johnson X-VCS-Revision: 247f865bf13016731beed5e2254c2528f971c763 X-VCS-Branch: master Date: Fri, 18 Jun 2021 06:57:42 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply X-Archives-Salt: c7d4fbab-488c-4011-8279-7af539ecd70c X-Archives-Hash: 6d6eea8210a67a781e6cf3b8737b4a4d commit: 247f865bf13016731beed5e2254c2528f971c763 Author: Robin H. Johnson gentoo org> AuthorDate: Fri Jun 18 06:55:14 2021 +0000 Commit: Robin H. Johnson gentoo 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 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.