Home
This guide is designed for new contributors (and beginners) who wish to learn everything necessary to easily install and contribute to Grace. We don’t assume that you have contribution experience or discord bot development experience.
Working on Grace is fairly easy and you don’t need to be an “expert”, but just knowing the basics might not be enough. You need to have at least an adequate understanding of programming. With that said, we don’t want to prevent anyone from contributing, yet if you are unable to code by yourself without our constant assistance we might ask you to practice programming and Python before continuing.
⚠️ Grace officially support Linux only. Although it should work on Windows and MacOS, it could have unexpected behavior or errors. Consequentially, this guide has been constructed around Linux (Ubuntu).The troubleshooting page contains common issues with Linux, MacOS, and Windows.
Grace requires Python 3.9 or higher but we recommend using the latest version as we try to keep it updated as much as possible. Download Python here.
If you’re not familiar with Python, they offer a collection of useful tutorials for beginner, intermediate, and advanced programmers. You can also find more information about Python through their documentation.
We follow rigorously the official styling guide (PEP0008) so it’s recommended to read it (at least the Code Layout and Naming Conventions) and refer to it when write code.
A virtual environment (venv) is an isolated Python environment. In other words, it allows you to isolate dependencies required by different projects from each other. This prevents version issues between projects and system tools.
In this example, we use virtualenv to create and activate the venv.
Commands
virtualenv venv
source venv/bin/activateExample
Tutorials
💡 Configuring a virtual environnement is optional but highly recommended.
Once Python is installed and you configured your virtual environment (optional) you have to install Grace decencies. We use setuptools to automatically install everything required.
When working on Grace, you want the installation to be editable, meaning you want your change to be applied without needing a new installation. To install the dependencies while making Grace editable, execute the command below.
Command
pip install -e .Example
Executed in a virtual environment
If you want to install Grace in production execute the command beneath.
Command
pip install .💡 All the commands have to be executed from the project root directory. If you decide to use a virtual environment, be sure that it is activated before completing this step.
The most important part of the configuration is your bot token. Without it will be impossible to communicate with discord.
To get your discord bot token, you must first create a discord application. Once you’ve successfully created your app, copy your bot’s token located in the bot section, then in the project root directory, edit or create .env and add DISCORD_TOKEN=<Your Token> (do not include the < >).
Don’t forget to invite your bot into your discord server to test it.
🚨 DO NOT SHARE YOUR TOKEN OR
.envWITH ANYONE. In case of accidental reveal, reset it as soon as possible.
The bot also requires discord Privileged Gateway Intents to be enabled. To do so, in your discord bot dashboard, go to the bot tab on the menu to the right and enable PRESENCE INTENT, SERVER MEMBERS INTENT, and MESSAGE CONTENT INTENT.
Grace requires a database to work. Lucky for you, everything is set up automatically upon installation and your first execution.
Follow this guide If you want to use another database then the default one configured automatically. Otherwise, you can skip that section.
Under construction
Grace comes equipped with a script to start and manage the bot. The script allows you to start the bot, create, destroy, and seed the database.
grace [-h] [-e {production,development,test}] [--sync | --no-sync] [command]
Commands
| Commands | Description | Notes |
|---|---|---|
| start | Starts the bot (ctrl+c to stop) | |
| db create | Creates the database and the tables | |
| db drop | Deletes, create and seeds the database. | DANGEROUS: All data will be lost |
| db seed | Seeds the tables (Initialize the default values) | |
| db reset | Deletes, creates and seeds the database. | DANGEROUS: All data will be lost |
Options
| Options | Description |
|---|---|
| -h, --help | Show the help message and exit. |
| -e {production, development, test} | Set’s the working environment (default is production) |
| --sync, --no-sync | Enable (default) or disable the command syncing. (Can accelerate the startup) |
💡 Use “development” when bringing changes to Grace (ex.
grace start -e development)
Example
Executed in a virtual environment with development configurations
In this section, we will visit and explain the purpose of the important components of the bot. We will see the file structure and the purpose of each main package.
grace
├── bot
│ ├── classes
│ ├── extensions
│ ├── helpers
│ └── models
│ └── extensions
├── config
├── db
│ ├── alembic
│ │ └── versions
│ └── seeds
├── docs
├── lib
├── logs
└── scripts| Folder | Purpose |
|---|---|
| grace | Project root directory |
| bot | Contains the extensions, helpers, classes, and models for the bot. |
| config | Contains the configuration scripts and the bot’s settings, environment, and database configurations. |
| db | Contains the database scripts seeds and migrations. |
| lib | Additional internal modules for the bot. |
| logs | Bot log file |
| scripts | Contains scripts to start and manage Grace. |
Whenever you commit to a project's default branch [main] or the gh-pages branch, open an issue, or propose a Pull Request, we'll count that as a contribution
Thus you can contribute by
- Proposing a new feature by opening an issue
- Reporting a bug by opening an issue
- Adding or improving a feature
- Fixing a bug, typo, etc
As per GitHub's explanation of a contribution, we consider that you have contributed to the development of Grace if you did any of those. That being said, there’s a small difference in recognition of contributions. Only someone whose Pull Request has been accepted and merged on the main branch will be displayed on the repository contributor list.
Create a new issue
If you find a problem with the documentation or the bot, search if an issue already exists, if no issue has been created for the problem, you can open a new issue. Be sure to select the appropriate templates.
Solve an issue
If you’d like to solve an issue, go through our issues and select the one that you’d like to solve. You can filter them by using the labels. When you find an issue you’d like to work on, be sure there’s no one assigned to it and that it’s not labeled not ready or wontfix.
When you're finished with the changes, create a pull request, also known as a PR.
- Label your PR as
ready for review - Be sure to link the issue if your PR is related to one.
Change may be required by the team before merging. If it’s the case, suggestions or comments will be given directly on the PR. It will also be labeled change needed.
- Resolve each conversation before asking for a new review.
- When ready, change the label to
ready for reviewand click on Ask re-request review.
Test your changes as much as possible with all use cases before creating a pull request. If you doubt some aspect of your changes (code, visual aspect, etc), don’t hesitate to discuss it or ask for help on the server.
⚠️ Ensure that your code respects the official Python styling guide (PEP0008)
Here are a few helpful tutorials to get started with Git, GitHub, and contributions