A big welcome and thank you for considering contributing to CSS' open-source projects! We welcome anybody who wants to contribute, and we actively encourage everyone to do so, especially if you have never contributed before.
- Getting Started
- Using the Issue Tracker
- Repository Structure
- Making Your First Contribution
- License
- Guidance
If you have never used Git before, we would recommend that you read GitHub's Getting Started guide. Additionally, linked below are some helpful resources:
If you are new to contributing to open-source projects on GitHub, the general workflow is as follows:
- Fork this repository and clone it
- Create a branch off main
- Make your changes and commit them
- Push your local branch to your remote fork
- Open a new pull request on GitHub
We recommend also reading the following if you're unsure or not confident:
This bot is written in Python using Pycord and uses Discord's slash-commands & user-commands. We would recommend being somewhat familiar with the Pycord library, Python language & project terminology before contributing.
We use GitHub issues to track bugs and feature requests. If you find an issue with the bot, the best place to report it is through the issue tracker. If you are looking for issues to contribute code to, it's a good idea to look at the issues labelled "good-first-issue"!
When submitting an issue, please be as descriptive as possible. If you are submitting a bug report, please include the steps to reproduce the bug, and the environment it is in. If you are submitting a feature request, please include the steps to implement the feature.
main.py: is the main entrypoint to instantiate theBotobject & run itexceptions.py: contains common exception subclasses that may be raised when certain errors occurconfig.py: retrieves the environment variables & populates the correct values into thesettingsobject
cogs/: contains all the cogs within this project, see below for more informationutils/: contains common utility classes & functions used by the top-level modules & cogsdb/core/models/: contains all the database ORM models to interact with storing information longer-term (between individual command events)tests/: contains the complete test suite for this project, based on the Pytest framework
Cogs are attachable modules that are loaded onto the Bot instance.
They combine related listeners and commands (each as individual methods) into one class.
There are separate cog files for each activity, and one __init__.py file which instantiates them all:
For more information about the purpose of each cog, please look at the documentation within the files themselves
-
cogs/__init__.py: instantiates all the cog classes within this directory -
cogs/archive.py: cogs for archiving categories of channels within your group's Discord guild -
cogs/command_error.py: cogs for sending error messages when commands fail to complete/execute -
cogs/delete_all.py: cogs for deleting all permanent data stored in a specific object's table in the database -
cogs/edit_message.py: cogs for editing messages that were previously sent by the bot -
cogs/induct.py: cogs for inducting people into your group's Discord guild -
cogs/kill.py: cogs related to the shutdown of TeX-Bot -
cogs/make_member.py: cogs related to making guests into members -
cogs/ping.py: cog to request a ping response -
cogs/remind_me.py: cogs to ask the bot to send a reminder message at a later date -
cogs/send_get_roles_reminders.py: cogs relating to sending reminders, to Discord members, about opt-in roles. (See Repeated Tasks Conditions for which conditions are required to be met, to execute this task) -
cogs/send_introduction_reminders.py: cogs relating to sending reminders, to Discord members, about introducing themselves. (See Repeated Tasks Conditions for which conditions are required to be met, to execute this task) -
cogs/source.py: cogs for displaying information about the source-code of this project -
cogs/startup.py: cogs for startup & bot initialisation -
cogs/stats.py: cogs for displaying stats about your group's Discord guild, as well as its channels & Discord members -
cogs/strike.py: cogs for applying moderation actions to Discord members -
cogs/write_roles.py: cogs relating to sending the message that contains all the opt-in roles, into the "#roles" channel
After you have found an issue which needs solving, it's time to start working on a fix! However, there are a few guidelines we would like you to follow first.
To ensure your changes adhere to the required functionality of this project, a test suite has been provided in the tests directory.
The test suite uses Pytest, and can be run with the following command:
poetry run pytestPycharm & VS Code also provide GUI interfaces to run the Pytest test suite.
In general, follow the formatting in the file you are editing. You should also run the static analysis linting/type checking tools to validate your code.
Ruff is a static analysis code linter, which will alert you to possible formatting mistakes in your Python code. It can be run with the following command:
poetry run ruff check .There are many additional flags to provide more advanced linting help (E.g. --fix).
See ruff's documentation for additional configuration options.
Mypy is a static type checker, which will alert you to possible typing errors in your Python code. It can be run with the following command:
poetry run mypy .Although there is a PyCharm plugin to provide GUI control & inline warnings for mypy, it has been rather temperamental recently. So it is suggested to avoid using it, and run mypy from the command-line instead.
PyMarkdown is a static analysis Markdown linter, which will alert you to possible formatting mistakes in your MarkDown files. It can be run with the following command:
poetry run python ./.github/workflows/scripts/remove_invalid_tables.py && \
poetry run pymarkdown scan . ; \
poetry run python ./.github/workflows/scripts/remove_invalid_tables.py --restoreThis command includes the removal of custom-formatted tables, as discussed in the "Markdown Linting Issues" section. This command will not run on Windows PowerShell! (Use CommandPrompt instead.)
The tools ruff & mypy can be run as normal from the command line (as long as you are within the poetry environment), however, PyMarkdown will incorrectly throw errors if run according to its own documentation. This is because some markdown files contain custom-formatted tables that PyMarkdown cannot parse.
Therefore, you must run this utility script before calling PyMarkdown to remove any custom-formatted tables from files:
poetry run python ./.github/workflows/scripts/remove_invalid_tables.pyThe below command will restore all markdown files back to their original states:
poetry run python ./.github/workflows/scripts/remove_invalid_tables.py --restoreCommit messages should be written in the imperative present tense. For example, "Fix bug #1".
Commit subjects should start with a capital letter and not end in a full-stop
Additionally, we request that you keep the commit subject under 80 characters for a comfortable viewing experience on GitHub and other git tools. If you need more, please use the body of the commit. (See Robert Painsi's Commit Message Guidelines for how to write good commit messages.)
For example:
Fix TeX becoming sentient
<more detailed description here>
Once you have made your changes, please describe them in your pull request in full. We will then review them and communicate with you on GitHub. We may ask you to change a few things, so please do check GitHub or your emails frequently.
After that, that's it! You've made your first contribution. 🎉
Please note that any contributions you make will be made under the terms of the Apache Licence 2.0.
We aim to get more people involved with our projects, and help build members' confidence in using git and contributing to open-source. If you see an error, we encourage you to be bold and fix it yourself, rather than just raising an issue. If you are stuck, need help, or have a question, the best place to ask is on our Discord.
Happy contributing!