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, scrutineers, 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 designer, administrator, or scrutineer.

In the wake of a series of election errors 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.

Hypothesis
A more robust and usable SecurePoll software system will make movement elections easier to manage, maintain, tally, and publish, resulting 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 of highest error generation).
 * Poll Design System: The current system used for designing and creating elections 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 (dupe detection) 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 an election, a group of "scrutineers" 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.

Workflow of SecurePoll
The SecurePoll software exists in one of a finite number of states depending on the lifecycle of the poll. These states are listed below.


 * 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.
 * 4) Vote 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 software entirely and recreate it from scratch.
 * 5) Voting period: Voting has commenced. Voting runs from the specified start date to the specified end date.
 * 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 here.

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 election will now be managed within a "wizard" (Special:SecurePollWizard). Upon initially going to Special:SecurePollWizard, the poll administrator will be presented with four elements:


 * 1) A list of currently running elections (have met start date but not end date)
 * 2) A list of pending elections (have not met start date)
 * 3) A list of previous, expired elections
 * 4) 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 election 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 elections will display tallied results (if already tallied and published). If the election has not been tallied, it will go to the (currently existing) scrutineer interface.

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.
 * 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).
 * 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).

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

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 a separate form.

Phase 3: Post-election Processing
TBD