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.

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 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 Possibly, but error generation is not as important here as risk. More errors does not equal higher risk. Philippe (WMF) (talk) 21:11, 9 April 2014 (UTC)).
 * 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)not really, in general the lists were just run and errors dealt with. Dupes aren't a problem in the list. Jalexander (talk) 21:15, 9 April 2014 (UTC) 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" I'd like to avoid this term. it is narrowly enwiki only. Philippe (WMF) (talk) 21:10, 9 April 2014 (UTC) 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
The SecurePoll software exists in one of a finite number of states depending on the lifecycle of the poll I would strike everything after "states". Philippe (WMF) (talk) 21:12, 9 April 2014 (UTC). These states are listed below.
 * 1) "Dormant" ? Philippe (WMF) (talk) 21:12, 9 April 2014 (UTC)
 * 2) Configured: An initial configuration has been entered, including vote eligibility criteria.
 * 3) 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.
 * 4) Ready to commence: Once the list of eligible voters has been created, SecurePoll waits until the specified start date.
 * 5) Vote deleted What about "Vote Aborted" or something that doesn't imply that a vote was made and then deleted. No vote was actually made in this instance. Philippe (WMF) (talk) 21:13, 9 April 2014 (UTC): 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. I'd say that we want to use a more descriptive term here, perhaps 'election (or poll) aborted/deleted'. A vote deleted sounds like votes were actually deleted which is the work flow below). Jalexander (talk) 21:19, 9 April 2014 (UTC)
 * 6) Voting period: Voting has commenced. Voting runs from the specified start date to the specified end date.
 * 7) 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. How is this different from your vote deleted stage above? I mean, obviously, one had votes cast and the other didn't, but there's no functional difference, right? Philippe (WMF) (talk) 21:14, 9 April 2014 (UTC) if we're going to separate out aborting before or after votes the term 'vote aborted or voting aborted' would make more sense here then above. Jalexander (talk) 21:19, 9 April 2014 (UTC)
 * 8) 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).
 * 9) Results: After the election administrators have finished the vote scrutinisation, the results of the poll are announced. This isn't a change of state for the software is it? That is, nothing functionally changes between the previous condition and this. It's just a change of state for the election. Oh, of course there is.  The vote tally. Philippe (WMF) (talk) 21:34, 9 April 2014 (UTC)

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 With less visibility some of this should still be visible for non admins as well, probably everything but the new poll button or a greyed out button. Jalexander (talk) 21:27, 9 April 2014 (UTC) 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)  What about a list of aborted elections? Philippe (WMF) (talk) 21:37, 9 April 2014 (UTC)
 * 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.

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

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 a separate form. If they are on both exclude/include lists exclude should override. This ensures less digging and falls over in the right direction. Jalexander (talk) 21:31, 9 April 2014 (UTC)

Phase 3: Post-election Processing
TBD