Elections Plugin


(Angus McLeod) #1

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:

  1. A “New Election” button will appear for election admins in the discovery nav button list.

    Screenshot at Aug 22 16-27-10

  2. 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_list site 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.title in server.*.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_message in server.*.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.

46

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.

50 AM

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.
    17 AM
  • If the elections nominee titles site 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.
    Screenshot at Sep 02 10-21-14

Nomination statements are identified by a Nomination Statement label that appears after the nominee’s titles on the nomination statement post.

22 AM

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.

    04 PM

  • 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.

    15 AM

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

Category based vote limits
Poll problem - exact vote numbers needed
Beginner’s Guide to Creating Discourse Plugins Part 6: Acceptance Tests
Adjust poll data manually - no user details import needed
(Tobias Eigen) #2

This looks fantabulous! Nice work. :rocket:

Is it stable enough to install on a production site? If not, can you give me access to your site so I can try it out there first, before I install on my site? I don’t currently have a sandbox.

The main question I have is whether we can incorporate handling of eligiblity requirements for positions into the voting system. Perhaps it can be done simply using a topic template for the category? If someone nominates themselves and is obviously not eligible, we’d then want to remove them and contact them to let them know. Before voting starts, that is. :slight_smile:

One other issue that I see is that the START ELECTION button might be a bit too tempting in that location for moderators. Could it be limited to just admins so moderators don’t accidentally click it? :wink:


(Angus McLeod) #3

I’ll pop it on a sandbox tomorrow

Yes. For my purposes it made sense to link to a resource where things like eligibility requirements are listed (the ‘details url’ - see above). However, I’m sure it will make sense for some people to add this directly to the election post. You’re thinking something like this right?

You can also just edit the post (if you have sufficient powers to edit someone else’s post).

Or are you thinking of ‘eligibility requirements’ in terms of Discourse properties of the user (i.e. trust level)?

Made that a setting. Default is that only admins can administer (create, update) elections.


(Christoph) #4

That’s how I understood it, at least that’s what I would find useful. More specifically: check eligibility to be nominated and check eligibility to vote. I suppose the best way to do this is group membership, not just TL or other default groups but custom groups. A typical scenario would be that the statutes of an association require that voters are members in good standing…


(Tobias Eigen) #5

Thanks, Angus! This all looks really great. I guess when I try the elections functionality out on your sandbox I’ll learn more about how it works and identify more sticking points. Thanks for addressing the START ELECTION moderator temptation issue. :wink:

As regards eligibility requirements - a description field (maybe that can be expanded/closed?) is a great idea and that can work for many use cases, instead of a link. How about a tickbox, e.g. “I have read the eligibility requirements and confirm that I meet them.” followed by a link to expand/close it?

BTW, did you look at the full election process I included in the post below? There is a screening step foreseen there, by a selection committee, to avoid wasting time of all members reviewing nominations that are not going to be considered. I like the full democracy concept you are developing here though and if the process is effectively handled by your plugin I am open to trying it without the screening step. Uneligible nominations can always be removed by us before voting begins.


#6

very good plugin my bro^^


(Roland) #7

Im using this on my site now. Seems to be a great addon.


(Tobias Eigen) #8

You might want to be careful with this on a live site as this is a new, in progress plugin. :wink:


(Angus McLeod) #9

How about, as first step to better supporting your process, I:

  1. Make self nomination an optional feature of each election, toggled in the ‘create election’ modal.

  2. Add a button, visible to ‘election admins’ only (i.e. admins if elections_admin_moderator setting is off; admins + mods if it is on), that reads “Add Nominee” and which opens a modal that allows the election admin to select from a list of users and then add them as a nominee?

Then you could handle any screening processes for nominees as you see fit. Does that work?

re the sandbox server, I’m waiting on a new domain; will try to get it up tomorrow (Friday) or this weekend.


#10

Is it possible to have the same election choose multiple people, or nominate other people (e.g. a group, i.e. all trust level 3 members)? We are choosing 5 leaders in our election that is done with the poll system


(Tobias Eigen) #11

I :heart_eyes_cat: 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?


(Angus McLeod) #12

Ok, I’ve created a new sandbox. Currently it has this plugin, Quick Messages and Question Answer on it.

Here’s an example election.

@tobiaseigen @Silvanus I can make you mods on the sandbox if you want to see the election admin features.

I haven’t added the features we’ve discussed yet (but you won’t see them if you’re not an election admin anyway), i.e.

  • Free text entry in the new election modal
  • Self nomination toggle
  • Add nominee button

After reading the linked topic, I still don’t entirely understand what your process is. But the simple answer to your question is that you can edit the poll in the first post of the election topic like you can any other poll.

I should clarify that the point of this plugin is to provide additional tools and UI elements specific to elections on top of what the Polls plugin provides. I don’t want to restrict the Polls plugin in any way. That would be counter-productive.

In addition to the features mentioned above, something else I’m curious about is how you are thinking about election ‘discovery’. Currently there is a list that is added to the discovery UI. You’ll see it when you go to the elections category in my sandbox.

Actually, if you are already running elections using topic based polls could you link them here? Seeing a real live example will help me (and others).


(Tobias Eigen) #13

ok - cool. I’m in. Feel free to give me election admin privs so I can see how that works.


(Angus McLeod) #14

I just pushed the Free text entry in the new election modal and deployed that to the sandbox.

Currently the text you enter in that box is initially added to the election post and also saved to a TopicCustomField. It’s stays appended to the post during the nominate period.

When the election actually starts and the post turns into a poll, I haven’t appended the free text message, based on the use case of using free text to describe the nominating process, which would distract at the time the poll is actually held. But this is just what occurred to me at the time and it’s easy to change. Let me know your thoughts on this.

I’ve made you a moderator.


(Angus McLeod) #15

I’ve added

Self nomination control toggle (for election admins)

Nominee management (for election admins)
Screenshot at Aug 25 17-11-33

Live on the sandbox (I can make you mod if you want to try it out).


(Tobias Eigen) #16

I tried this out on your sandbox and it’s looking good! I will keep thinking about it, and show it to my colleagues who want to run elections on our site.

One minor bug I noticed - if I select MANAGE NOMINATIONS and add myself as a nominee, and then select NOMINATE MYSELF I am able to add myself again. Oops. The nomination popup also has an issue with displaying the category name which I am guessing you are already aware of.

Would it be possible for you to add the ability for nominees to provide a short elevator pitch for why they should be chosen. It could be a small text box allowing a limited number of characters (say 200?). The pitch would then be displayed by their name in the poll, like in the example below.

Also, would be nice if the name were an @ mention, so voters could click to see the user card instead of clicking away during the election. Generally speaking, I think the less clicking away the better.

  • @tobiaseigen - I have been wanting to be the grand poobah my whole life and would throw my whole life into it. My former experience as pooh bear and paddington make my an ideal fit far superior to all others.
  • Angus Young - As AC/DC lead rocker, I am already a grand poobah. Vote for me to add another feather to my cap.
  • Jimmy Cliff - The harder they come, as they say, and poobah’s are as hard as they come. Vote for me so I am the first Jamaican grand poobah!

0 voters


(Angus McLeod) #17

:+1: bugs fixed.

Yes, I was thinking along similar lines :+1:

Just pushed these updates:

Nominees are listed with avatar, username and excerpt of their statement (if they’ve composed one). Clicking the avatar or the @mentioned username opens a user card.

Once nominated a nominee sees an ‘Add Statement’ button on the election post. Clicking that button opens a composer (with a ‘Nomination Statement’ label). The nominee composes and posts as normal.

22 PM

Once they’ve posted, the election post (i.e. the first post in the topic) automatically updates with a linked excerpt to their statement.

The length of the post excerpt is currently set at 100, but that can easily be made a setting.

Nominees get a little ‘nominated’ badge next to their name.

51 PM

Removing a nominee removes them from the nominated list in the election post and removes their ‘nominated’ label but doesn’t remove their ‘statement’ post (if they’ve made one). If the nominee is re-added in the future their statement post will automatically be … reinstated (i.e. they won’t have to re-compose / link it if they are incorrectly removed).

Next step is to add the same details (avatar, @mention and link to statement) to the poll itself (currently only the nominee list looks like the above).

Here’s an example of the above on my sandbox.


(Tobias Eigen) #18

This is coming together nicely, Angus - nice work. Only suggestion at this stage is to rename “Nominated” to “Nominees”.

Pretty cool that the election admin can remove a nominee and then add them again, and have the pitch still show up at the top. It’s quite seamless.


(Sam) #19

This is really nice @angus!

Would making the results private (admin-only, I suppose) be within the scope of this plugin? My community runs elections regularly, but we wouldn’t want a visible running tally for the in-progress elections or even for the totals at the end to be public.


(Angus McLeod) #20

Agreed. Done.

You mean all users are allowed to vote, but only admins can see the results? This would be an edit of the polls plugin itself, as that handles the voting. Possible to do though.