This is an automated email from the ASF dual-hosted git repository. gstein pushed a commit to branch trunk in repository https://gitbox.apache.org/repos/asf/steve.git
commit d09cfa96da3a38fe40c84c58354482748c88de74 Author: Greg Stein <[email protected]> AuthorDate: Mon Feb 23 09:47:02 2026 -0600 docs: improve comments and documentation in create-election.py and election.yaml.sample Co-authored-by: aider (openrouter/x-ai/grok-code-fast-1) <[email protected]> --- v3/server/bin/create-election.py | 27 +++++++++++++-------------- v3/server/bin/election.yaml.sample | 31 ++++++++++++++++--------------- 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/v3/server/bin/create-election.py b/v3/server/bin/create-election.py index e95ce1c..59ab13a 100755 --- a/v3/server/bin/create-election.py +++ b/v3/server/bin/create-election.py @@ -17,6 +17,11 @@ # specific language governing permissions and limitations # under the License. +""" +Script to create an election from a YAML definition file. +Reads election metadata, issues, and voter records, then populates the database. +""" + import argparse import datetime import pathlib @@ -87,10 +92,7 @@ def main(yaml_file): if not isinstance(record, list): raise ValueError('record must be a list of pid values') - ### revising how we manage the two database instances and their - ### connections. no transactions for now. partial Elections, and - ### issues are fine for now. - # Start transaction for safety + # TODO: Re-enable transactions for safety once database setup allows. # pdb = steve.persondb.PersonDB(DB_FNAME) # pdb.db.conn.execute('BEGIN TRANSACTION') @@ -116,35 +118,32 @@ def main(yaml_file): # Open a PersonDB using the existing DB from the Election pdb = steve.persondb.PersonDB(election.db) - ### HACK: we opened PDB using the existing DB from the Election. - ### It does not have the cursors specific to PersonDB. For now, - ### hack the bugger in. - ### q_person: SELECT * FROM person ORDER BY pid + # HACK: Opened PDB using existing DB; lacks PersonDB cursors. + # q_person: SELECT * FROM person ORDER BY pid pdb.q_person = pdb.db.cursor_for('SELECT * FROM person ORDER BY pid') - # Get all persons + # Get all persons for validation all_persons = pdb.list_persons() all_pids = {person.pid for person in all_persons} - ### hack for testing. map OLD pids to their newer equivalent + # Temporary hack: Map old PIDs to newer equivalents for testing. + # TODO: Remove once PID data is fully migrated. _REMAP = { 'iroh': 'wells', - } + } # Validate and add voters from record for pid in record: - pid = _REMAP.get(pid, pid) + pid = _REMAP.get(pid, pid) # Apply remapping if needed if pid not in all_pids: raise ValueError(f'PID {pid} from record not found in person database') election.add_voter(pid) _LOGGER.info(f'Added {len(record)} voters to election[E:{election.eid}]') - ### we aren't doing transactions right now. omit this. # pdb.db.conn.execute('COMMIT') _LOGGER.info(f'Election[E:{election.eid}] fully created from {yaml_file}') except Exception as e: - ### we aren't doing transactions right now. omit this. # pdb.db.conn.execute('ROLLBACK') _LOGGER.error(f'Failed to create election from {yaml_file}: {e}') raise diff --git a/v3/server/bin/election.yaml.sample b/v3/server/bin/election.yaml.sample index d3a47a3..9d2d4f9 100644 --- a/v3/server/bin/election.yaml.sample +++ b/v3/server/bin/election.yaml.sample @@ -1,31 +1,32 @@ # Sample YAML file for defining an election to be created via create-election.py # Copy this file, edit as needed, and run: python create-election.py <your_file.yaml> +# Note: All PIDs must exist in the person database. Timestamps are Unix epoch ints. election: - title: "Board Election 2024" - owner_pid: "alice" # Apache ID of the election owner - authz: "pmc" # Optional authorization level - open_at: 1704067200 # Optional Unix timestamp for opening (2024-01-01T00:00:00) - close_at: 1706745599 # Optional Unix timestamp for closing (2024-01-31T23:59:59) + title: "Board Election 2024" # Required: Human-readable election title + owner_pid: "alice" # Required: Apache ID of the election owner + authz: "pmc" # Optional: Authorization level (e.g., 'pmc', 'members') + open_at: 1704067200 # Optional: Unix timestamp for opening (2024-01-01T00:00:00) + close_at: 1706745599 # Optional: Unix timestamp for closing (2024-01-31T23:59:59) -issues: - - title: "Approve Budget" - description: "Vote yes/no/abstain on the proposed budget." - vtype: "yna" # Yes/No/Abstain vote type +issues: # Required: List of voting issues + - title: "Approve Budget" # Required: Issue title + description: "Vote yes/no/abstain on the proposed budget." # Optional: Details + vtype: "yna" # Required: Vote type ('yna' or 'stv') - - title: "Elect Board Members" + - title: "Elect Board Members" # Example STV issue description: "Rank candidates for board seats using STV." - vtype: "stv" # Single Transferable Vote type - kv: - version: 1 # KV format version - labelmap: + vtype: "stv" + kv: # Required for STV: Key-value metadata + version: 1 # Format version + labelmap: # Candidate mappings (label -> name) a: "Alice" b: "Bob" c: "Carlos" d: "David" seats: 3 # Number of seats to elect -record: # List of PIDs eligible to vote (must exist in person database) +record: # Required: List of eligible voter PIDs (must exist in person database) - alice - bob - carlos
