SecurePoll 2014 Redesign

This document describes software design changes for the Secure Poll extension.

Rationale
The SecurePoll extension is an extremely difficult to use system that has been known to (unintentionally) encourage errors and considerable stress, tedium, and difficulty to poll designers, administrators, and publishers (though not with voters).

Most of the more difficult or tedious tasks using SecurePoll are handled manually: command line execution of scripts, hand-building of machine-readable XML files, manual database manipulation, and off-line trawling of spreadsheets are common artifacts of the process. At no point does the software do anything to prohibit errors from creeping in nor does the software encourage or aid the poll designers and administrators.

In the wake of a series of errors in polls caused by the above and because the Wikimedia Foundation Board of Trustees has expressed a desire to improve these processes, several parts of the process are being redesigned (or, "actually designed") in order to improve the overall experience of those involved.

Meta note: We are using the terms "poll" and "election" and "vote" somewhat interchangeably here. They are not interchangeable. I suggest that we standardize on these definitions:
 * Election: An election is "a formal and organized choice, by vote" [in a poll].
 * Poll: A poll is the mechanism by which you put questions to the community (this is consistent with the naming of the extension)
 * Vote: A vote is an individual decision by a voter, as cast in a poll.

So, the phrasing would be: You are in an election period, and taking a poll, by voting. Philippe (WMF) (talk) 21:40, 9 April 2014 (UTC)

Hypothesis
A more robust and usable SecurePoll software system will make movement elections easier to manage, maintain, tally, and publish, resulting in an overall increase in satisfaction by all participants of a movement election.

Work Phases and Project Scope
During an initial meeting about the project the team was treated to a walkthrough of how SecurePoll works and how elections are created and managed. Discussion was also given to the overall problems surrounding SecurePoll and a brainstorming session about how to improve the software was held. During this time, three areas that were ripe for improvement were identified:

Work was determined to be split into phases, with phase 1 (Poll Design) entering design and implementation first (this was determined to be the point where the most errors were generated, with some of the errors leading to the need to restart polls from scratch during the voting period.).
 * Poll Design System: The current system used for designing and creating polls relies heavily on manual creation and manipulation of XML files. This is prone to error as there are no error checks.  Further, the process is innately user-hostile.
 * Voter List Preparation: The list of eligible voters in any election is pre-determined before a poll opens. This list is generated through a series of expensive database calls (sometimes taking over 48 hours to complete).  Once done, the list is then manually processed and in some cases eligible voters are added (e.g., Wikimedia Foundation employees are added to the list of eligible voters in Trustee elections).
 * Post-election Scrutinization: After the voting period of a poll has ended, a group of poll administrators examine all votes cast and attempt to remove duplicates. The software provides some help here but not enough, and the work is done through a tedious process that mixes off-line spreadsheet work and on-line vote striking/unstriking.

Additional work to do in a parallel track to the above:


 * Logging: Any admin-related actions taken on a poll (e.g. poll creation, changes to poll configuration, vote striking, translations) must be logged. This log should be viewable by any poll administrator. Is there a reason not to make this publicly viewable? Philippe (WMF) (talk) 21:33, 9 April 2014 (UTC)

Workflow of SecurePoll
Each poll exists in one of a finite number of states:
 * 1) Configured: An initial configuration has been entered, including vote eligibility criteria.
 * 2) Creating list of eligible voters: SecurePoll is comparing the vote eligibility criteria against the set of all users to create the list of eligible voters. This can take quite some time to run.
 * 3) Ready to commence: Once the list of eligible voters has been created, SecurePoll waits until the specified start date. Note: at this point, it should still be possible to make changes - i.e., to delay the vote start by 1 day or something. Philippe (WMF) (talk) 09:07, 13 April 2014 (UTC)
 * 4) Poll deleted If, before the voting period has started, the poll was found to be set up incorrectly, election administrators may delete the poll from the interface and recreate it from scratch.
 * 5) Voting period: Voting has commenced. Voting runs from the specified start date for the specified number of days.
 * 6) Poll aborted: If there were found to be grave, irreparable errors in the poll, the poll can aborted during the voting period. The poll will need to be recreated from scratch.
 * 7) Voting period ended aka Vote scrutinisation period: The voting period has ended. In this state, votes can be manually struck by the election administrators if they are determined to be illegitimate (e.g. duplicate votes).
 * 8) Results: After the election administrators have finished the vote scrutinisation, the results of the poll are announced.

A graph illustrating the transition between these states is available in this image.

This workflow represents the steps that SecurePoll must go through to successfully work through a poll, and these states may or may not be explicitly visible to end users depending on the decisions of the team.

Phase 1: Poll Design Wizard
The design of an poll will now be managed within a "wizard" (Special:SecurePollWizard). Upon initially going to Special:SecurePollWizard, the poll administrator will be presented with five elements:


 * 1) A list of currently running polls (have met start date but not end date)
 * 2) A list of pending polls (have not met start date)
 * 3) A list of polls that were aborted during voting
 * 4) A list of previous, expired polls
 * 5) A big button saying "Create new poll"

Clicking the "Create new poll" button will take the user to the Poll Design Wizard (see "Poll Design Wizard", below).

Clicking on the links of any pending poll will take the user to the design wizard as well, but in this case it will be pre-populated with the current information (e.g., title, candidates, etc.). The admin will be able to edit the parameters of the poll and/or add new candidates.

Links to expired poll will display tallied results (if already tallied and published). If the poll has not been tallied, it will go to the (currently existing) scrutineer interface.

We want to make sure we keep some of the options that are available now like the ability to see the voter list from this screen no matter what stage of the election it is (during/after). Jalexander (talk) 21:27, 9 April 2014 (UTC)

Poll Design Wizard
(Note that the mockup may not accurately reflect what will be in the final product as it was built by examining poll XML files, which may or may not reflect accurate data structures.)

For the most part, the wizard is self-explanatory (or described in the mockup itself). Some notes:


 * Poll Run Dates: Rather than provide two date pickers ("start date" and "end date") which would require a additional error logic (e.g., "is end date before start date") and to reduce confusion ("is this date crossing the UTC dateline?"), a single "start date" picker is used with a pull down to select the number of days to run the election.
 * Admins: The names of the admins are stored in the XML with pipe ("|") separation. Commas are indicated in the field; pipes may be preferred based on allowable MediaWiki usernames.  Ideally, this would be a smarter interface (search for username, add to list) to reduce error.  However, this interface (the Design Wizard) will only be used by a handful of people (probably less than 10) so a bit of "living dangerously" can be allowed, given the low amount this project has been resourced. What would these admins have access too? Just the vote tallying/scrutinizing/translations of this election? Compared to the 'user rights' who can create polls? Do the people with the create poll user right have the ability to do all of the above admin stuff too? Or only if they are added to the list? Do these admins have the ability to change the poll config even without the local userright? Jalexander (talk) 21:27, 9 April 2014 (UTC)   Is there a need for this user group? What function would it fulfill? Philippe (WMF) (talk) 21:51, 9 April 2014 (UTC)
 * Column Labels: The number and type of column labels are actually dependent on the Poll Type selected.  These fields should swap out display based on the type of poll selected (the mockup assumes a three-point radio range poll).  Column labels should be editable but start with a set of sane defaults.
 * Options: Ideally, we can allow for additional fields per option (e.g., "Real Name", "User Name", "Home Wiki", etc.). Given that the project has a low resource allocation, however, this is considered out-of-scope at this time.  Clicking the "+ New Option" button will insert a new, blank option into the list.  Blank options, when submitted, should be discarded.

Saving the poll will:
 * In the case of a new poll:
 * Write the poll to the database
 * Generate applicable cryptography keys
 * Display to the admin the correct private key that will unlock and tally the poll results. This is the key that is sent to the publishing official (a 3rd party) (Currently, this key is generated on the command line and then inserted into the XML). Is this the 'one and only time' to get this key? Jalexander (talk) 21:27, 9 April 2014 (UTC)
 * Create a composite log entry that:
 * Indicates that the poll was created and by whom (single line)
 * Has additional lines for each element created (for later analysis against changes)
 * In the case of an existing poll:
 * Write changes to the database, possibly adding or removing candidates.
 * Create a composite log entry that:
 * Indicates that the poll was changed and by whom (single line)
 * Has additional lines for each change that was made

Phase 2: Voter Eligibility
The following criteria are routinely used in polls in the Wikimedia community and must be supported in a vote eligibility interface:
 * 1) User must not be blocked on p or more wikis.
 * 2) User must have at least n edits before a specified date.
 * 3) User must have at least m edits between two specified dates.
 * 4) User must not have any of the following flags.
 * 5) User is eligible to vote if they have any of the following flags.

These criteria have the following intent, respectively:
 * 1) User is in good standing in the Wikimedia community as a whole.
 * 2) User has a history of activity at some point in the past.
 * 3) User is active in the present timeframe.
 * 4) User is not a bot.
 * 5) User is a member of a specific set of users who are allowed to vote irrespective of other criteria (e.g. system administrators or staff). pink

The election administrator must have the option to choose which of the criteria he wishes to use in his election.

Important to note the difference between global/local here that is going to have to be taken into account basically everywhere. Jalexander (talk) 21:31, 9 April 2014 (UTC)

The logic for the criteria, if they are all used, is 1 ∧ 2 ∧ 3 ∧ 4 ∨ 5; if this formula evaluates to true for a particular user then they are eligible to vote, if it evaluates to false then they are not. This essentially means that in order to be eligible to vote, you must either meet all of the first four criteria or meet the fifth.

The software must also support the ability for election administrators to manually include and exclude voters in the eligible voters list. This will supported through separate forms; the exclude form will always override the include form.

Phase 3: Post-election Processing
TBD