CONTRIBUTING.md

Contributing

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.

Quick Links

• Getting Started
• Using the Issue Tracker
• Repository Structure
• Making Your First Contribution
• License
• Guidance

Getting Started

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:

• GitHub git guides
• git - the simple guide
• Getting Git Right (Atlassian)

If you are new to contributing to open-source projects on GitHub, the general workflow is as follows:

1. Fork this repository and clone it
2. Create a branch off main
3. Make your changes and commit them
4. Push your local branch to your remote fork
5. Open a new pull request on GitHub

We recommend also reading the following if you're unsure or not confident:

• How To Make A Pull Request
• Contributing To An Open Source Project For The First Time

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

Using the Issue Tracker

We use GitHub issues to track bugs and feature requests. If you find an issue with TeX-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.

Repository Structure

Top level files

• main.py: is the main entrypoint to instantiate the Bot object & run it
• exceptions.py: contains common exception subclasses that may be raised when certain errors occur
• config.py: retrieves the environment variables & populates the correct values into the settings object

Other significant directories

• cogs/: contains all the cogs within this project, see below for more information
• utils/: contains common utility classes & functions used by the top-level modules & cogs
• db/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

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 TeX-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 TeX-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

Making Your First Contribution

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.

Running tests

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:

uv run pytest

Pycharm & VS Code also provide GUI interfaces to run the Pytest test suite.

Code Style

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

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:

uv 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

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:

uv 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

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:

uv run ccft-pymarkdown scan-all --with-git

This command includes the removal of custom-formatted tables. See the CCFT-PyMarkdown tool for more information on linting Markdown files that contain custom-formatted tables.

Git Commit Messages

Commit 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>

What Happens Next?

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

License

Please note that any contributions you make will be made under the terms of the Apache Licence 2.0.

Guidance

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!