Git Product home page Git Product logo

votum's Introduction

Votum
Add
View Source on GitHub

Need help? Have a suggestion, comment, or problem? Join the Discord server.

Votum

A Discord bot for managing small party voting systems such as a council or small group who want to deliberate on matters democratically. Contributions and suggestions are welcome.

Looking for a bot that provides quick on-the-fly poll-based votes to your entire community? Check out Poll Dancer

Commands

Admin commands

These commands can only be run by someone with the Manage Server permission, or with a role named Votum Admin.

Command Description
!Council [name] Create a council (or rename) in the channel you run this in, with an optional name.
!Council remove Remove a council from the channel you run this in.
!CouncilStats Displays some statistics about your council.
!SetWeight [user/role] [weight] Sets the vote weight for users with a role or a user. See Weighted Voting
!VoteWeights Display the current vote weights. See Weighted Voting
!config [key] [value] Configures a setting in this council. See the table below.
!config [key] $remove Sets this setting back to its default.

Configuration Points

Key Value type Description Default
councilor.role role Define a role that councilors must have to vote. Otherwise, anyone that can see the channel can vote and will be counted for the majority count. None
propose.role role Restricts proposing motions to users with this role only (in addition to the councilor role). None
dictator.role role Any time a user with the dictator role votes, the motion will pass or fail immediately based on how they voted. None
user.cooldown number Set the number of hours a councilor must wait between proposals. (Killed motions do not trigger the cooldown). 0
user.cooldown.kill boolean Whether or not killing motions should trigger the cooldown. false
motion.expiration number Set the number of hours a motion can remain active. 0
announce.channel channel Designate a channel where all passed and failed (not killed) motions will be logged. None
on.passed.announce channel A channel that announces passed motions only. None
on.killed.announce channel A channel that announces killed motions only. None
on.failed.announce channel A channel that announces failed motions only. None
councilor.motion.disable boolean Whether or not creating new motions is disabled in this council (only accepts forwarded motions) false
motion.queue boolean If enabled, motions can be created when another is active and will be queued, automatically starting when the current motion ends. false
majority.default majority-type The default majority for motions. Fraction or percentage. 1/2
majority.minimum majority-type The minimum majority councilors can create motions with. 1/2
majority.reached.ends boolean Whether or not motions end as soon as majority is reached. Otherwise, all councilors will need to vote. true
on.finish.actions json A set of actions that will take place when a motion resolves. See Finish Actions None
vote.weights json A map of User/Role IDs to the amount of votes that they are worth. Allows councilors to be worth different amounts of votes. See Weighted Voting None
reason.required.yes boolean Whether or not the user must provide a reason with a positive vote. true
reason.required.no boolean Whether or not the user must provide a reason with a negative vote. true
reason.required.abstain boolean Whether or not the user must provide a reason with a neutral vote. false
create.deliberation.channels boolean Whether or not to create deliberation channels for each motion. false
keep.transcripts boolean Whether or not to keep transcripts of the deliberation channels before they are deleted. false

Councilor commands

Command Description
!motion See the current motion.
!motion <motion text> Call a motion with the given text.
!motion [options] <motion text> Call a motion with Motion options
!motion kill Kill the current motion. (Only admins or the motion author can do this).
`!yes aye
`!no nay
!abstain [reason] Abstain from voting with an optional reason.
!lazyvoters Mentions any council members who haven't voted on the current motion yet.
!archive [range] Allows you to view past motions. Provide a range of numbers to view a summary, or provide a single number to view a motion.
!archive export Exports your council's data as a JSON file.

Motion Options

Motion options are special flags you can put at the beginning of your motion to change options about the motion. Right now, the only options available are for changing the majority type.

Option flag Aliases Type Description
majority m majority type A percentage or fraction indicating the majority type.
unanimous u boolean Specifies the motion should be unanimous (shortcut for -m 100%)
Example

To start a motion with 2/3rd majority, you could use the commands (all are equivalent):

  • !motion -m 2/3 Motion text goes here
  • !motion --majority 2/3 Motion text goes here
  • !motion --majority 66% Motion text goes here

Unanimous motion (all are equivalent):

  • !motion -u Motion text goes here
  • !motion --unanimous Motion text goes here
  • !motion -m 100% Motion text goes here
  • !motion -m 1/1 Motion text goes here

Voting

  • Multiple councils can be defined in one Discord server, as the councils are based on channels.
  • Upon a tie, the motion will remain forever until someone breaks the tie.
  • The councilor cooldown is not triggered if the motion is killed.
  • When a motion expires, the outcome is determined by majority votes. If there are more "yes" than "no" votes, it will pass, and vice-versa.
  • If you do not set a Councilor role, the total number of voters is determined by who can see the channel. It's recommended that you set a role for councilors so that you can be sure that only possible voters count towards the total number needed for majority.
  • Server admins (or people with a role called Votum Admin) can always create motions.

Quick set-up guide

  1. Pick a channel that your councilors will deliberate in.
  2. Run !Council My Council to mark this channel as a council. (Change "My Council" to whatever you want it to be named.)
  3. Create a role for the members of your council and give it to your voters. Then, run !config councilor.role RoleNameHere.
  4. Run !motion This is my first motion. You're all done! Check out the other configuration options above for more advanced use.

Finish Actions

With the on.finish.actions configuration point, you can supply custom JSON configuration that tells Votum what to do with your motion once it resolves. Most prominently, you can forward your motion into other councils (based on the majority type) with potentially different options. Use this link to be taken to a form where you can generate a valid JSON configuration for this option. The actions have these fields:

field type description
action string enum (forward) The action. Only forward is supported.
to snowflake The discord ID of the channel of the new council
atMajority? number A number between 0-1 that will filter this action from triggering unless the motion resolved with this given majority (optional)
options? string Motion options

Weighted Voting

With the vote.weights configuration point, you can supply a JSON mapping between User and Role IDs to the amounts of votes that they will cast. If a councilor has more than one of the roles, their votes will be added together.

The provided JSON should be an object which has role/user ID string keys mapped to numerical values. For example, this is a valid mapping:

{
  "113691352327389188": 5,
  "400057282752151565": 2,
  "601529861244321793": 4,
  "401864080446717952": 8
}

To learn how to get the user and role IDs, check out this help article.

<style> h1:not([id]) { display: none; } </style>

votum's People

Contributors

brmetzger avatar dependabot[bot] avatar evaera avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

votum's Issues

Make vote counts appear in announcements even through forwarded motions

Should probably change it from state being possibly undefined to another field which just invalidates the state (like depth: number). Then check that this is 0 everywhere state is checked for being undefined now. Depth should increase every time the motion gets forwarded. Need to leave the undefined checks though, so as to not break old motions.

Add a special case for announcement posts, where the previous votes are added up and counted.

Motions passing without meeting the required majority

The scenario:
A motion has the majority set to two-thirds. The expiry time is 24 hours.
After 24 hours, the votes are 5 in favour, 4 against. The motion passes despite it not receiving the two thirds majority.
The solution:
When a motion expires, it should not pass based on a simple majority. It should pass based on the default majority, or, if one is set, the custom majority.

Multiple majority types

I absolutely love your bot. Do you have idea when you will be able to resume working on the multiple majority types? And do you have any plans on making this available for larger councils?

Don't show votes on announcement posts

Would be nice if there was an option to delete the votes and only keep the final results of a motion once it concludes. Just to reduce clutter if you have everything in one channel only.
-- LoyaItyLeader

Question

Is it possible to set the councilor role to more than one role?

Allow proposers to not have to be council members as well.

We are looking to have our Server Admins be the only ones who can start a motion, but those users are NOT allowed to be voting council members. I'd like to remove the restriction that the proposer must also have the council role. Or at least a way to mark an admin as a non-voting council member.

Option to Disable Vote Embed Adding Each Member/Reason

The current voting embed that happens when a member votes has all the previous members votes and comments. For someone like me who may have 100+ voting members that is going to get CRAZY big. I'd suggest that the vote does not show that kind of detail. It should still be maintained for transcript, etc. And perhaps a new command like !votetally or something that can trigger a list by admins or something. But I don't think think the running names and comments are required.

Lazy voters message doesn't split

An error occurred while running the command: DiscordAPIError: Invalid Form Body
content: Must be 2000 or fewer in length.
You shouldn't ever receive an error like this.
Please contact eryn#0001

Multiple majority types

2/3rd, 4/5th, etc configurable majority types.

Ideally, there should be some mechanism to override this per-motion and indicate it on the motion itself.

!motion end

Ends motion based on current votes taking majority into account

Requested by Aaron Schock#0518

Ability to Add and Remove Users from Weighted Voting by Command

It would be really nice if we could add a new user to the Weighting by command. (!config add.weight 2312931929321912 3) and remove them from the Weighting in similar fashion !config remove.weight 12312312312312)

Where %1 is the userid and %2 is the vote total.

That will mean we can script that process more easily and removes the headache of maintaining a JSON file.

Votes inside deliberation channels

Make it so if creating deliberation channels is true, then you should be able to vote in that channel and not where the motion was created.

Need to be able to mark a council as weighted or not weighted.

We have a Committee that starts the amendment process. Those people have a role called Committee Member and Council Member. Their Discord ID's have been assigned weighted votes. The Committee stars the process and then when approved it JSONs over to the Chamber Floor for deliberation and voting. We want the weighted voting to ONLY apply in the Chamber Floor, not the committee room. So maybe an easy fix is to have an allow weighted voting option for the council creation? And if its checked it uses the JSON and if not it doesn't and assumes 1 for 1. Obviously it would be great to have separate weights for each council if we wanted...but not a requirement.

Progress channel mode

There should be an option for votes to be displayed in a form similar to Poll Dancer, where instead of the voting progress being displayed every time someone makes a vote (which can cause a lot of clutter in the debating channel), a dedicated proposal channel holds that same information, but edits that message every time someone changes their vote - which could be handled either when:

  1. A user votes through !aye / !nay / !abs commands, and a smaller acknowledgment is displayed; or
  2. A user votes through reactions, if enabled by the Votum Admin, which will update the vote - only available for voting options that do not require a reason attached.

I could also work on a PR for this if you're interested!

Motions that give roles on pass

Two new motion options:

elect: user
role: role

New configuration points:

  • election.enabled
  • election.roles: json map (role id -> term limit). Roles not in the map are not electable. Role is removed after term limit is reached.

Deliberation Channel Issues

Here is some initial feedback/changes for the Deliberation Channels:

  1. If a motion was given a title, that title should make it into the channel as either a description of the channel or as a note in the channel. Otherwise it just has the motion number.
  2. The channel should be made inside of the category that the council lives in, not a new category named the same as the Council name.
  3. The channel should inherit permissions from the category it is in. We allow read-only roles to watch the deliberations. Or perhaps add a config item for "watcher" that we can give permissions to.
  4. The bot does not seem to be listening to votes in the deliberation channel. Ideally all business could be handled in the deliberation channel for that motion. (Which would let us have multiple votes going at the same time in the future.)

New Feature: Delete previous motion embed

Not sure where to put a feature request, but it would help clean up the voting channels if the previous motion embed was deleted as the new one is posted after a vote.

Multiple groups, 1 vote each

Here's a basic description:
Council consist of multiple subgroups. Each subgroup gets a single vote, but any of the members of that subgroup could, in th heory, send it.
Subgroups are identified by roles. However, there are other roles which don't apply to the subgroups (they apply to positions within the subgroups).
So, can it be done, and do you want to?

set council defaults

when creating new councils in new channels, would be nice to have some inherited defaults shared across the server/channel category

No output from commands without council & improve archive command behavior

There are two suggestions. However, since each of these issues is quite minor, I am condensing both into one issue.

  1. All commands do not print any text when a council does not exist yet.
    Expected Behavior:
    Input: !motion newTextHere
    Input: !config reason.required.no true
    Input: !CouncilStats

Expected Output:

A council does not exist for this channel.

Observed Output:

No Output
  1. archive command truncates motion description without a visual queue to signal the truncation.
    Expected Behavior:
    Input: !motion "this is a long string of motion text which exceeds 45 characters long and therefore should be truncated."
    Input: !motion "this is not a long string."
    Input: !archive #1-#2

Expected Output:

#1 Passed | this is a long string of motion text which...
#2 Passed | this is not a long string.
To view a full motion, run archive #1 where 1 is the number of the motion you want to view.

Observed Behavior:

#1 Passed | this is a long string of motion text which ex
#2 Passed | this is not a long string.
To view a full motion, run !archive #1 where 1 is the number of the motion you want to view.```

Chair/Speaker/President role and ability to restrict admins from changing config

  1. There should be a 'Chair' configuration point which can be assigned to a role, which has the authority of the Votum Admin role, except it only has that authority in the council it is assigned to.
  2. There should be a configuration point which if toggled on, will prevent any user except for the owner, a Votum Admin, or the 'chair' from changing the config of a council (or killing motions that are not their own).

Poll mode

I was thinking about adding a poll command to Votum to replace Poll Dancer, and allowing emoji reactions for votes and essentially being more of a "chill mode" - poll doesn't end when a majority is reached and instead only has a set time, allows multiple options, and doesn't require reasons.

#2 has been open since Votum came out, and I still think having a list of options instead of just yes/abs/no would be a good idea, I'm just not sure the best way to implement this from a user experience perspective.

add unvote option

an !unvote command would be nice to retract a !yes, !no, !abstain vote on a !motion

also an option to disable !abstain as an option for all motions.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.