docs: add an Election States help page - #1502
Conversation
Adds docs/help/election_states.md, answering what draft / finalized / open / closed / archived mean and what you can do in each. Most "can I still do this?" support questions are really state questions, and there was no page covering it. Leads with a table of the two things people actually need -- can voters vote, and can I still edit -- then a section per state, how elections move between them, and a short FAQ. Checked against the code rather than written from assumption, which corrected a few things worth calling out: - Editing is allowed only in draft (editElectionController), not "restricted once open". Finalize locks the election permanently. - Voting is allowed only in draft and open (castVoteController); everything else is rejected with "Election is not open". That is the crisp difference between finalized and open. - Draft is the test mode, and finalizing deletes the test ballots automatically (finalizeElectionController calls innerDeleteAllBallotsForElectionID). - Draft skips voter authentication, the voter roll, assertVoterMayVote, and ballot_updates. Worth saying plainly: a draft test does NOT confirm your voter restrictions work, which is the opposite of what an admin would assume. - State changes are lazy rather than scheduled (updateElectionStateIfNeeded), so finalizing with no start time opens the election immediately, and an election with no end time never closes on its own. - Manual open/close is only available when no start/end times are set (setOpenStateController: "Cannot open or close an election with scheduled start and end times"). The two routes are exclusive, not alternatives. nav_order is 1 so it sits first in the section -- it reads as the orientation page the others assume. Happy to move it if you'd rather it sat elsewhere; it's a one-line change. Internal links use the .md form, matching help/how_to_enable_beta_features.md's existing usage -- jekyll-relative-links rewrites them to .html for the site, and they also work when reading the source on GitHub. Verified by building the site locally: renders with the table and callouts intact, lands first in the sidebar, and both Related links resolve.
✅ Deploy Preview for bettervoting ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Warning Review limit reached
Next review available in: 47 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
1 participant
Adds a help page for the five election states — draft, finalized, open, closed, archived — and what you can do in each.
There wasn't a page covering this, and it's the answer to a lot of support questions: can I add a candidate now? can I change the end date? why can't my voters see the ballot? Those are all really "what state is my election in?"
It leads with the two things people actually need:
…then a section per state, how elections move between them, and a short FAQ.
Written from the code, which corrected a few assumptions
I checked each claim against the source rather than describing states generically, and several things came out differently than I'd have guessed:
editElectionControllerrejects anything else with "Election is not editable" — so finalizing locks the election permanently, not just while voting runs.castVoteControllerrejects the rest with "Election is not open". That's the crisp difference between finalized and open.finalizeElectionController→innerDeleteAllBallotsForElectionID).assertVoterMayVote, andballot_updates. The page says this plainly, because the natural assumption is the opposite: if you test a restricted election in draft and the ballot goes through, that hasn't confirmed your restrictions work.updateElectionStateIfNeeded). So finalizing with no start time opens the election immediately, and an election with no end time never closes on its own.If any of that doesn't match intent, the page is the thing to change, not the code — happy to adjust.
Notes
nav_order: 1puts it first in the section, since it reads as the orientation page the others assume. One-line change if you'd rather it sat elsewhere..mdform, matchinghelp/how_to_enable_beta_features.md's existing usage —jekyll-relative-linksrewrites them for the site, and they also work when reading the source on GitHub.