How to Contribute¶

This page will go over everything someone needs to know to contribute to EnduraBot's code.

See hosting yourself for an explanation of how to get EnduraBot running on your machine.

Information¶

Licensing¶

EnduraBot is released under the MIT license. The gist is that anyone may use any of EnduraBot's code for any reason, even for commercial purposes.

The stipulations are:

1. Such persons must include a copy of the MIT license as it exists in the repository in any codebase using EnduraBot's code.
2. I cannot be held liable for any hypothetical bad thing which may occur as a result of using EnduraBot's code. This is because I provide such code "AS IS" without a warranty of any kind.

If you decide to contribute to EnduraBot's codebase, any such code you provide shall be released under the same license.

Workflow¶

The workflow for developing EnduraBot is a simplified and abbreviated version of GitFlow.

For a contributor, the flow will more-or-less be:

1. Fork the EnduraBot repository and clone it to your machine.
2. Make a new branch off of your forked dev branch which represents the change(s) you want made.
3. Make your change(s).
4. Commit your change(s) to the branch you've created.
5. Push your branch to your fork on GitHub.
6. Make a pull request on the actual EnduraBot repository requesting that your forked feature branch merge into the EnduraBot dev branch.

Languages¶

EnduraBot is written in Python using the discord.py library. The only exceptions are GitHub specific files, markdown files (such as the README), and Docker files.

Guidelines¶

Make an issue for new features or code refactoring¶

If you'd like to add new functionality, or refactor portions of the codebase, please make an issue to dialogue with me first.

The feature and/or refactor may not be desirable, and I don't want you to spend hours of work on something for me to reject the PR.

Command organization¶

cogs/user_cmds.py is designed for simple, self-contained commands. Commands with greater scope should be given their own file in cogs/.

Tasks vs. listeners¶

Files in tasks/ are for code that runs at set times or in set intervals. listeners/ are for code that reacts to some kind of event fired by Discord's API (e.g someone sends a message, a user joins the server).

Hard coding¶

Do not hard code something in a PR if an existing variable for the item is available somewhere in the data/ folder. New variables are also more than okay to create; the relevant _example file in data/ simply needs to be updated in the PR.

Styling¶

There are no formal style requirements; just please make your code look more-or-less like code around it (or, if in it's own file, look similar to code that performs the same function). Contributors who wish to make a PR to improve the uniformity and standard-conformance of code styling are encouraged to do so.

Command permission checking¶

All new commands must include the following decorator:

@app_commands.check(check_permissions)

With check_permissions being made available via the following import:

from utils.permissions_checker import check_permissions

This is what allows data/permissions.json to function. check_permissions is a function defined at utils/permissions_checker.py.

Miscellanea¶

Command types¶

If you review the documentation for discord.py, you'll notice that the documentation sometimes writes code like this:

@bot.command()
async def foo(ctx, arg):
    await ctx.send(arg)

Whereas throughout EnduraBot code is written like this:

@app_commands.command(...)
async def test(self, interaction: discord.Interaction):
     await interaction.response.send_message(...)

In short, the former is for text commands whereas the latter is for application commands. Discord strongly encourages developers to move away from text commands, though it seems Discord and discord.py continue to support them. As such, EnduraBot only uses application commands.

Any contributor wishing to create a text command should make an issue to dialogue with me first.

Git¶

A rudimentary understanding of Git is necessary to contribute. You are generally expected to know how to create repositories, clone existing repositories, make branches, commit to branches, add remotes to your repositories, pull new code from a remote repository to your local one, and push new code in your local repository to a remote one.

If you are completely unfamiliar with Git I suggest 2 things:

1. Watch the Git and GitHub - Full Course video on YouTube; it's free and taught by an ex-FAANG¹ senior software engineer. You do not need to watch the full thing; just getting to the 30 minute mark will give you a very strong foundation.
2. Look for a GUI that abstracts Git, such as Git Fork.