==================
openstack/election
==================

This repository contains OpenStack Elections reference documents
and tooling to run elections.


Election officials process
==========================

=============
PTL Elections
=============

Selecting Election Dates
------------------------

Things to keep in mind when selecting election dates:

* At least 48 hours in between email deadline and poll start
* Consider extra-atcs approval deadlines
* Should start around R-4 for nominations period
* Allow at least a week for nomination period

``setup-election-config`` can be used to pick some obvous dates that need to be
check by the election offiicals and TC

Preparation
-----------

As early as possible but at least a month before election starts:

* Edit elections details (timeline, cycle timeframe):
  * edit configuration.yaml
* Prepare new election, e.g.:
  * tox -evenv -- create-directories
* Commit to update website
* Update Release Schedule

A couple of weeks before election starts
* Send 'PTL Election Season' email
  * tox -e venv -- template-emails election_season


PTL Candidacy Round
-------------------

When PTL Candidacy start
* Send 'PTL Nominations Kickoff' email
  * tox -e venv -- template-emails nominations_kickoff

During the PTL Candidacy round:
* Validate candidacy, e.g.:
  * tox -evenv -- check-all-candidacies, or
  * tox -evenv -- ci-check-all-candidate-files candidates/release/project/candidates , or
  * tox -evenv -- check-candidacy change_id
* To +2 a candidate:
  * check commit link is indeed valid
  * check filename is email address
  * cursory check the candidacy statement
* To +Workflow, checks the previous +2 details, find another commits using --limit 5 (optional)

* Check candidate list and fix badly generated names through changes to the exception.txt file or
  requesting the candidate to update thier OSF member profile.

Once the email deadline is reached:
* Ask the TC chair to tag the governance repository
* Generate the electorate rolls.  This generates the rolls for all project
  teams even if they aren't going to hold an election.
  * tox -evenv -- generate-rolls

A couple of days before the candidacy submission ends:
* Render statistics and send 'Motivation call for PTL candidacy round', e.g.:
  * tox -evenv -- render-statistics
* Send 'PTL Nominations Last Days' email
  * tox -e venv -- template-emails nominations_last_days

When PTL Candidacy submission ends:
* Send 'PTL Nominations End' email
  * tox -e venv -- template-emails end_nominations

* When the tag is available, generate ATC rolls, e.g.:
  * tox -evenv -- generate-rolls
  * Compare ATC rolls with at least one other election official

PTL Election Round
------------------

When PTL Election begins:
* Create CIVS page ( https://wiki.openstack.org/wiki/Election_Officiating_Guidelines#Running_the_election_itself )
* Upload rolls
  * CIVS has a maximum number of electorate emails you can upload at a time without crashing, limit to 500
    at a time
* Send 'PTL Voting Kickoff' email
  * tox -e venv -- template-emails voting_kickoff

A couple of days before the PTL Election ends:
* Send 'PTL Voting Last Days' email
  * tox -e venv -- template-emails voting_last_days


When PTL Election ends:
* Close the election and udpate the results:
  * tox -evenv -- close-election ptl
  * edit doc/sources/pike/ptl.yaml to set election winners to True
* Commit the change and review the results
* Send 'PTL Results' email
  * This is doc/source/results/release/announce_ptl.rst generated by
    building the docs: toc -e docs
    After doc/source/results/release/ptl.yaml has been created and updated
* Update governance repo:
  * tox -e venv update-governance -- --governance-repo ../governance/

============
TC Elections
============

Selecting Election Dates
------------------------

Things to keep in mind when selecting election dates:

* Needs to conclude by S-3 (3 Weeks prior to OpenStack Summit)
* Allow for at least 48 hours between email deadline and polling begininning
* Allow at least a week for nomination and campaign periods

``setup-election-config`` can be used to pick some obvous dates that need to be
check by the election offiicals and TC

Preparation
-----------

As early as possible but at least a month before election starts:

* Edit elections details (timeline, cycle timeframe):
  * Edit configuration.yaml
* Commit to update website
* Update Release Schedule

A couple of weeks before election starts
* Send 'TC Election Season' email
  * tox -e venv -- template-emails election_season


TC Candidacy Round
------------------

When TC Candidacy starts:
* Send 'TC Nominations Kickoff' email
  * tox -e venv -- template-emails nominations_kickoff

During the TC Candidacy round:
* To +2 a candidate:
  * check candidate profile using https://www.openstack.org/community/members/
  * check filename is email address
  * cursory check the candidacy statement
* To +Workflow, check the previous +2 details

A couple of days before the candidacy submission ends:
* Send 'TC Nominations Last Days' email
  * tox -e venv -- template-emails nominations_last_days

When TC Candidacy submission ends:
* Send 'TC End Nominations' email
  * tox -e venv -- template-emails end_nominations


Once the email deadline is reached:
* Ask the TC chair to tag the governance repository
* Generate the electorate rolls.
  * tox -evenv -- generate-rolls


TC Campaigning
--------------

The TC election includes a period after the candidates are defined but before
the election, for candidates to answer questions from the community.  Open this
with:
* tox -e venv -- template-emails campaigning_kickoff

TC Election Round
-----------------

When PTL Election begins:
* Create CIVS page
  * Enable detailed ballot reporting
* Upload rolls
* Send 'TC Voting Kickoff' Email
  * tox -e venv -- template-emails voting_kickoff

A couple of days before the TC Election ends:
* Send 'TC Voting Last Days' email
  * tox -e venv -- template-emails voting_last_days

When TC Election ends:
* Close the election
* Run: tox -e venv -- close-election tc
  * edit doc/source/pike/tc.yaml setting the winners to 'True'
  * Commit change & push review
* Send 'TC Results' email
  * This is doc/source/results/release/announce_tc.rst generated by
    building the docs: toc -e docs
    After doc/source/results/release/tc.yaml has been created and updated
* Update reference/members in governance repository
  * Add new members
  * Remove 'chair' & 'vice-chair' from file
  * Commit change & push review
* Update tc-election-summary.py with election statistics
* [Optional]Send 'TC Election Statistics'