Repo: GitHub - angusmcleod/discourse-elections
This uses the Polls plugin as a base and adds controls and features specific to running elections.
Enabling and Settings
Elections are administered by “Election Admins”. By default, election admins are site admins. All moderators can be made election admins by toggling the elections_admin_moderator site setting.
- To do: allow any user to be designated an ‘Election Admin’.
Elections can be enabled on a category basis in Category Settings > “Category is used for elections”. If elections are enabled for a category:
-
A “New Election” button will appear for election admins in the discovery nav button list.
-
A list of elections with the ‘nomination’ or ‘poll’ status (see below about statuses) can be added to the category discovery list below the navigation controls if the
elections_nav_category_listsite setting is turned on (default is off).
Overview
An election is run in a topic; the ‘Election Topic’. The first post of the Election Topic lists the nominees for the election and holds the poll in which the winner is determined; the ‘Election Post’. The Election Post has buttons that appear after its contents that allow normal users and Election Admins to participate in and run the election; the ‘Election Controls’.
Elections have three statuses: Nomination, Poll and Closed Poll (*note I will use ‘status’ and ‘stage’ interchangeably in this description). When an election is first created it has the Nomination status. Once an election has more than 2 nominees an Election Admin can change the status to ‘Poll’. This generates a poll in the Election Post with the Nominees as the poll options. The Election Admin ends the election by closing the poll; the Closed Poll status.
Creating an Election
Election admins can create a new election by clicking ‘New Election’ in the category discovery list controls. All fields you can fill out in the New Election modal can be edited after the election is created.
-
Position (required): This is the position the election is for. The position is used in the Election Topic title as per
election.titleinserver.*.yml. -
Nomination Message (optional): This text is added at the bottom of the Election Post (see below) when the election has the “Nomination” status (see below). If no nomination message is added while creating a new election, a default message will be added so that the post will not be empty (see
nomination.default_messageinserver.*.yml). This default message can be edited or removed entirely after the election is created. -
Poll Message (optional): This text is added at the bottom of the Election Post when the election has the “Poll” status.
-
Allow Self Nomination (optional): This setting turns self nomination off / on for each election. Default is off.
Filling out the New Election modal and clicking ‘Create’ will create a new Election Topic in the category the ‘New Election’ button was clicked.
Election Post
The first post in the Election Topic is the ‘Election Post’. The election post is automatically generated once the New Election form is filled out. This post is where the nominees are listed, where the poll is held, where the nomination and poll messages are displayed, and where the Election Controls appear.
-
The Election Post is authored by the default system user. Selection of the election post author is a feature on the To do list.
-
Changes to the Election Post do not count as ‘Revisions’ (aka ‘edits’) to the post. If they did, the post would quickly end up with an unreasonably high number of revisions.
-
It is recommended that you do not edit the Election Post directly, however editing is still enabled as a backup measure.
Election Controls
The Election Controls are:
-
Toggle Nomination (“Nominate Yourself” or “Withdraw Nomination”). This button is visible to all users if the “Allow Self Nomination” setting is turned on for the election.
-
Add Statement. This button is visible to the nominees in the election. Clicking it will open a composer where the nominee can add a nomination statement.
-
Manage Election. This button is visible to Election Admins. See below about the Manage Election modal.
-
Start Election. This button is visible when the election status is "Nomination. It is a shortcut to change the status from “Nomination” to “Poll”.
Election Management
An Election Admin can manage an election once it starts in the Manage Election modal. This modal allows you to edit all the properties set in the New Election modal (see above) plus two more:
-
Status. This is where the election status can be set. Any of the three statuses - Nomination, Poll and Closed Poll - can be selected at any time, as long as the minimum criteria is met for the status.
-
Nominee Selection. This is a standard User Selection box. Adding and removing users will add or remove those users as nominees in the election. Nominees can be added or removed by an Election Admin at any point in the election process.
Each property in the Manage Election modal is independent. If you change the property, the ‘Save’ button to the right will be enabled, and will display the status of the save to the right.
As this plugin is interdependent on both core Discourse and the Polls plugin, there are various points at which failure can occur. I’ve attempted to isolate those points of failure. If a save does fail, the error will be caught and you should see a human readable error message and a code reference for debugging purposes. e.g.
If you change a property and close the modal without saving your changes, the changes will not be registered. You can make multiple changes to the same property or different properties in one go.
Nominations
Nominees, whether self-selected or admin selected, are listed in the Election Post. If the Allow Self Nomination setting is on, any user can add and remove themselves as a nominee during the “Nomination” stage. Election Admins can add or remove nominees at any stage.
Nominees can add a nomination statement by clicking the ‘Add Statement’ control and composing a post. The nomination statement appears as a post in the Election Topic and a linked excerpt is added next to the nominee’s entry in the Election Post. Any edits to the nomination statement will be reflected in the excerpt in the Election Post.
Nominees are identified:
- Within the election topic by a ‘certificate’ avatar flair.
- If the
elections nominee titlessite setting is turned on (default off) nominees are identified outside (only outside) the election topic by an 'Nominee for {{position}}" title which is linked to the Election Topic. This is not a normal Discourse title, as it appears in addition to any normal Discourse title the user holds.
Nomination statements are identified by a Nomination Statement label that appears after the nominee’s titles on the nomination statement post.
If a user is removed as a nominee the nominee avatar flair and any relevant nomination statement label will automatically be removed. The nomination statement itself (i.e. the post) will remain. If the user is re-added as a nominee they will automatically regain their avatar flair within the Election Topic and the nomination statement label will automatically re-apply to any existing nomination statement they made.
Poll
The Poll stage of the election works like a normal Discourse Poll, with the nominees as options for the poll. Like in the Nomination stage, any updates to the nominees or the nominee’s statements, is automatically reflected in the poll options.
In the results view, only the nominee’s usernames are used.
Closing the poll automatically changes the Election Statues to “Closed Poll”. Conversely, changing the election status to “Closed Poll” in the Manage Election modal automatically closes the poll.
Other
-
When an election status is changed to “Poll”, and when it is changed to “Closed Poll”, nominees are sent notifications.
-
Users can post in an election topic as normal, however if a user tries to post another poll in an election topic, it will fail.
To do
- Restricted self nomination, i.e. allowing self nomination on the basis of user properties such as trust level.
- Allow any user to be designated as an Election Admin
- Allow selection of the author of the Election Post
- Additional notifications
- Email notifications
- Nominee avatar flair selection
- Nominee badges and titles
- Topic list filters for Election Topic properties, e.g. Status
Full suite of tests
this very much! I don’t want to give too much more feedback before actually seeing the thing, but what about adding a spot for the pitch for each candidate within the poll?
bugs fixed.
