Administration

• 1: Concluding an Election
• 2: Creating an Election
• 3: Running an Election

1 - Concluding an Election

Completing the Election

Once the end date for the election is past, it is time for the Election Officers to conclude the election. This has two steps: computing the candidate rankings, and publishing the election results.

Computing the Rankings

After the end_datetime, Election Officers will be presented with a button on the Administrator Console to compute the election rankings.

Clicking that button does two things. First, it calculates the preference election mathematical results according to the configured election method, displays those results, and saves them to the database. Second, if delete_after is set, it deletes all of the encrypted links between voters and ballots as an additional privacy measure.

Once the election is calculated, it may not be “re-opened” by extending the end date.

Publishing the Results

The candidate rankings computed by Elekto are absolute mathematical rankings, and do not take into account organizational rules such as employer, role, or diversity quotas in the elected body. Some organizations also require the election to be certified by another committee. As such, the raw election results are visible only to the Election Officers.

To share the election results with all voters, create a results.md file. This is a simple, markdown-formatted file with no special headers. You add text in it to share the election results according to the rules of your organization.

What about Tie Votes?

In a preference election, two candidates with an identical ranking result in a tie. While Elekto uses special algorithms to prevent tie votes (such as, but default, Schultze), certain combinations of ballots result in an unbreakable tie, particularly in elections with low numbers of ballots.

In the case of a tie, it is up to your election rules to decide how to handle it. Usually, this means a runoff election.

2 - Creating an Election

The Election Directory

Create a new election in Elekto by creating a directory under the primary elections directory defined in the ELECTION_DIR configuration variable. What makes it an election directory or not is the presence of an election.yaml file; directories without this file will be ignored. This directory may be nested (e.g. elections/2021/TOC), but may not be nested under another election directory (one that has an election.yaml in it).

Anyone with appropriate permissions on the repository may create an election directory. Usually, creating the directory and file are the first actions of the selected Election Administrators.

Generally, after creating the directory, administrators create an election.yaml, election_desc.md, and voters.yaml file.

Election Administrators

Administrators are Elekto users who have special permissions to manage an individual election. Each election must have at least one, and can have any number although practically few elections require more than three. Administrators need not have any control of the underlying infrastructure, nor do they need rights on other elections. They need not even be qualified voters.

How election Administrators are selected is up to the organization running the election and its management of repository change permission. As far as Elekto is concerned, the people listed in election.yaml are the Administrators regardless of how they got there. Like Voters, Administrators log into Elekto with their OAuth IDs.

The election.yaml File

This YAML file is the main file that creates and configures an election. It contains multiple configuration variables, most of which can be changed at multiple times during the election. This file is required for the election to be recognized by Elekto, and if it has errors the election will not appear in the Elekto UI.

See the sample elections in elekto.meta.test for examples of these files.

election.yaml variables

name: Display name of the election. Required, changeable.

organization: Group for which this election is being run, for display purposes. Required, changeable.

start_datetime: datetime that voting for the election starts, in UTC time. At this datetime, the Vote button will be enabled automatically. Required. Changeable, but changing it after the election has already started can cause votes to be recorded or discarded improperly.

end_datetime: datetime that the election ends, in UTC time. At this time, the Vote button will be disabled automatically. Required. Changeable until the election ends and a winner has been calculated, after which changes to this field will have no effect.

no_winners: number of potential winners in the election, for display to the administrators. Required, changeable.

allow_no_opinion: True/False. Can voters choose not to rank some candidates? Required, changeable until the election begins, after which changes to this field may cause votes to be counted incorrectly.

delete_after: True/False, whether to delete the encrypted links between voters and ballots once election results are calculated. Extra voter privacy measure. Required, changeable until results are calculated.

show_candidate_fields: List. A list of additional display fields for the candidate information pages. Labels must match the candidate profile fields exactly, or the data will not be displayed. Optional, changeable at any time.

election_officers: List of Oauth IDs of the election officers, determining who they are. Required, changeable at any time. Election officers need not be voters.

eligibility: Text to display in the “eligibility” section of the UI, for voter information. Optional, changeable at any time.

exception_description: Text to display before the Request Exception link. Optional, changeable at any time.

exceptions_due: Datetime (in UTC) when exception requests will no longer be accepted, and the Exceptions button will be disabled. Can be any date before the end of the election. Required, changeable. If your election does not allow voter exceptions, then set this to the date you create the election.

The election_desc.md File

This file contains a Markdown-formatted description of the election for voter information purposes. Since this information is displayed directly above the list of candidates and the voting controls, it’s generally a good idea to limit it to about 1/3 page of text. If you have more election details than that, consider summarizing and linking off to a page on your own website.

This description should include, at a minimum:

• A description of what’s being decided in the election
• Who is hosting the election
• Contact information for questions

Ideally, it will also include:

• links to voter and candidate eligibility requirements
• link to candidate nomination process
• a short version of the election timeline

The voters.yaml File

The voters file contains a list of Oauth IDs of the qualified voters for the election, as a simple yaml list. If you wish to create an election before you have pulled the list of voters, then create an empty list until you add the voters.

Voters may be added at any time, until the end of the election. Voters may also be removed at any time, but if a voter is removed from the file after they have already voted, their ballot will not be deleted. As such, if voters need to be removed after an election has begun, it’s generally a good idea to abort the election and start a replacement one.

The contents of this file determine whether users see themselves as eligible to vote or not when they log into the UI. Voters are not otherwise notified when their status changes.

References

• Elekto test elections
• Kubernetes elections
• Knative elections

3 - Running an Election

An Elekto election includes a pre-election phase and an voting phase. Depending on your actual election process, the pre-election phase may be unnecessary or handled entirely outside Elekto. If so, ignore the pre-election phase instructions below.

A Note on Notifications

Elekto does not send notifications via email or other messaging to anyone. As such, it is up to your election administrators or officers to send out notifications using your normal community channels. All community members can check their current status and the status of the election at any time using the web UI, but they will not receive messages or reminders.

As such, when this Guide talks about sending reminders or notices, it is talking about action by the Election Officers or other community members.

Pre-election Phase

Two things happen between the time the election is announced and the time that voting starts. One is adding voters and acting on exceptions, and the second is adding nominated candidates.

The pre-election phase begins when the election is created in Elekto, and ends when voting starts.

Managing Voters

Voters are added to an election by populating the voters.yaml file. Obtaining a list of voters is up to you and your organization, as different groups have vastly different eligibility processes. Many CNCF projects obtain a list of voters by filing a ticket requesting a data pull from DevStats, CNCF’s contributor metrics system.

Once you have obtained a list of qualified voters and added them to voters.yaml, you should use your organization’s communications channels to announce that voters can now verify their status. Voters will be able to log into Elekto and check whether they are Eligible or not via the UI. If they find they are ineligible, they can request an exception (see below).

Until the election starts, you can freely add and remove voters from voters.yaml as your election rules dictate. We recommend that voters be sorted alphanumerically to make editing the list of voters easier. Elekto will ignore YAML comments, sort order, and even duplicates in the file.

Voter Exceptions

Organizations may allow people to challenge their voter ineligibility. Sometimes this is because the voter list process is error-prone, or it can be because some voter criteria are difficult to measure empirically. Based on the Kubernetes project, the term for requesting a ballot when the original voter list did not allow an individual to vote is a “voter exception”.

If your voter exception requests are public, then they can be handled via pull requests against the voter list. However, in Kubernetes and other projects, the exception requests are confidential, in order to spare members from embarrassment if their request is declined. For this reason, Elekto provides a mechanism for potential voters to request an exception through the UI.

The list of exceptions is available via the Admin screen in the UI. Access it by clicking the Admin button in the Election Information screen, which should be visible if you are an election officer and logged in.

From here you can see the list of requests. To keep track of which ones you have taken action on, you can click the button to indicate that the requests have been reviewed. This UI does not add voters whose exception requests are granted, however. To make voters eligible, you will need to modify the voters.yaml file in the repository. The requests screen is for tracking only.

Adding Nominated Candidates

Candidates get added to the Elekto system when they have completed and merged profiles. All profiles will need to be merged before the election begins. How candidates are nominated and qualified and their profiles are reviewed is entirely up to your organization; Elekto cares only that the candidate.md file has the correct formatting and naming.

To support this, it’s usually helpful for the Election Officers to create a nomination-template.md file as a template for potential candidates to copy. EOs are are usually also in charge of helping candidates with completing their profiles and sending out reminders to the community about nomination deadlines.

For more about candidate profiles, see the Candidate Guide.

Voting Phase

At the date and time indicated in the start_datetime setting, voters will be able to start voting. No further administrative action is required. During the voting phase, administrators should have little to do other than adding people to the voters list from the Exceptions.

The Administrator Console

Changing the Voters List While Voting

Most organizations continue to accept Voter Exception requests during the voting phase, so that voters can be added and cast ballots even if they are slow to check their status. Closing exceptions about three days before voting ends can be a good timeline.

There is no problem adding voters at any time before the end_datetime of the election. Once additional voters are merged into voters.yaml, they are immediately able to vote.

Removing voters from the list, however, is a bad idea once voting has started. Once a voter has cast a ballot, there is no way to delete their ballot. While administrators can check whether a particular voter has voted, deleting a voter can be subject to a race condition. That said, problems with duplicate voter IDs (e.g. one voter with two Github accounts) can be cleared up by deleting accounts during voting if you have the active cooperation of the voter.

Modifying the Election While Voting

Administrators can make changes to election.yaml and other settings during the election. Not all such changes are effective or wise, however. What follows are some notes on settings it makes sense to change during the voting phase. Settings that are not mentioned should not be changed. Elekto provides no guardrails here, though; administrators are technically able to change anything they wish.

• election_desc.md, eligibility, exception_description: descriptive fields can be changed any number of times without worry.
• end_datetime: you can change the end time of the election in order to give more time for voting as long as the election has not yet been concluded.
• exceptions_due: you can also extend the Exceptions deadline until the election concludes.
• no_winners, discard_after: these fields affect election conclusion, so they can be changed until then.
• election_officers: officers can be added and removed from the election during voting.

You may also make changes and updates to candidate profiles during voting. However, adding or removing a candidate during voting would make it impossible to correctly compute the ballots. As such, if you need to change the list of candidates after voting starts, you will need to halt the election and hold a new one.

Retrieving and Canceling Ballots

During voting, voters may cancel and recast their ballot. Adminstrators, however, have no mechanism to cancel any voter ballot, or assist voters who have forgotten their passphrase. This is intentional, in order to prevent Election Officers from manipulating the election.