Contributing - shinyfinder/chatot-smogon GitHub Wiki

Note

The source code for Chatot has been moved to the main Smogon repo and does not pull from this repository anymore. However, this wiki is still updated to reflect the current codebase. Legacy instructions for working with the code in this repo can be found on the Legacy page.

If you're looking to add Chatot to your servers, refer to the Quickstart guide or the more in-depth User Guide instead.

Software

  • Docker
  • v.22.x LTS or later installed of NodeJs
  • pnpm - npm install -g pnpm
  • Git
  • Recommended: WSL (Windows users)
  • Recommended: VS Code
  • Recommended: ESLint (VS Code extension)

Once you have installed these dependencies, you'll want to obtain a copy of the code. Please confer with chaos for access.

Installation

  1. Obtain a copy of the source code with git clone https://github.com/smogon/smogon.com.git
  2. Open a terminal and navigate to installation_directory/smogon.com. Install the dependencies via pnpm install.
  3. If you haven't already, create a file called .env inside the ./smogon.com directory. The keys needed in this file can be found in the README(https://github.com/smogon/smogon.com/tree/master/chatot). This file contains the environment variables required for the bot to run. Never give out the values in this file! Please refer to the discord.js documentation for setting up your bot application and adding the bot to your server(s) to obtain the values for your application.

Additions to the environment variables will need to be reflected in config.ts. These values are accessed within the bot as botConfig.VARIABLE_NAME.

For full functionality, the bot needs access to all 3 privileged intents (guild pressences, guild members, and message content).

  1. Ensure your absolute filepaths for PG_CACHE and SQL_CACHE will not be committed with changes to this code. If needed, you can do so by ignoring the files in your personal gitignore located at project_directory/.git/info/exclude. You can put them wherever; I chose the chatot/src/sql folder and added them to my personal gitignore. If the files are not in the smogon.com directory, you can skip this step.

  2. Ensure Docker is running on your machine. You don't need to have any containers running, it just needs to be open (power saving mode is fine).

  3. In a terminal in the ./smogon.com/ directory, SSH into production with pnpm tunnel. This will create a live connection to the Smogon server, which can be killed with ctrl+c.

  4. With the terminal from the above step still open, open a new terminal in the ./smogon.com/ directory, and start the bot with pnpm chatot.

  5. You should see that the bot is now online in Discord. To confirm it is responding to commands, type /ping within Discord and send. The bot should respond with "Pong!".

Dev Loop

Once you have everything setup, your typical startup procedure will be:

<Ensure Docker is running>
pnpm tunnel
pnpm chatot

Your running instance of Chatot can be turned off with Ctrl+C within the terminal that's running it. This will trigger the shutdown sequence (in reality this sequence is triggered by sending a SIGTERM to the program, but we in turn send that automatically on SIGINT), backing up any inserts to the databases and logging out of Discord. Please give the program a few moments to finish. When done, the program should return on its own. Keep in mind spamming Ctrl+C will cause the program to terminate immediately without backing up your information or shutting down cleanly.

Commentary

Using the bot

This bot uses slash commands (a subset of application commands). Deployment of these commands is handled during startup of the bot witihn the /src/helpers/updateState.ts file. This script detects any changes in your command definitions and (re)deploys them as appropriate. Each command type is instantiated as a class defined within /src/helpers/commands.ts. The class you choose determines the scope of the command. Generally speaking, global commands are available in all guilds the bot is in, and guild commands are only available in the list of specified guild IDs.

Note that if the bot is in dev mode (as specified in your .env; it should always be in this mode!), the specified guild array will be overwritten with the dev guild id specifed in the .env, which means you only need to be concerned with inputting the production values to the command definitions.

Database connections

Chatot primarily uses Postgres for its storage; the schema is defined in the schema.sql file. However, certain features (such as /verify and C&C/CA monitoring) require a mySQL connection, as that is the schema used by Xenforo. Please refer to the forum's source code for that schema; the specific tables used by Chatot can be found within the respective functions.

Chatot now runs in dev mode under testcontainers, eliminating the need for devs to install and manage their own SQL databases. This requires Docker to at least be installed (you do not need to create a Docker image, but you can if you want for your own purposes). On shutdown, the program will create a database backup file in the directory of your choosing (PG_CACHE and SQL_CACHE env variables). If your filepath is within the smogon.com directory, add the files/path to your personal gitignore file, located under project_directory/.git/info/exclude so you don't pollute the commit history. When you restart the bot, it will read from these files to populate the databases.

Commands that access the Dex information require SSH access to the production server. Please confer with chaos for your options in obtaining this access.

Thus, there are 3 database connections in use at the moment: (1) postgres container (pgPool), (2) postgres ssh (sshPool), (3) mysql container (mysql). If you are inserting/deleting from tables you'll need to use the container connections. The containers are the ones that read from the backup files. If you want to do a select query from the production information, you can drop in sshPool for pgPool within the code. At this time there is no ssh support for mysql. Testing of features that rely on a connection to the forum database are pretty much accomplished via tests. Tldr just use pgPool and mysql for postgres and mysql calls respectively.

Usage of Postgres and MySQL is beyond the scope of this guide. However, you can find guides to these tasks across the internet, such as the official Postgres manual.

Code organization

Comments are provided within the *.ts files to offer a more precise understanding of what the code is doing line-by-line. For the sake of providiing a general overview, the core components of the bot are separated into different directories within /src. Any additions you make to the code will likely go within this folder. Commands (user interfaces with the bot) and events (triggers the bot listens for) are separated into their respective directories. Further, each command and event is given its own file. While it may be possible to oranize the files into further subdirectories, each feature being given its own file allows for easier debugging and isolation of code. Any functions used by the commands or multiple files are stored in the /helpers directoy.

While writing a command, you should always keep in mind any unit tests you can write for it (especially if the command requires a database call). There are plenty of examples throughout the code base (see: /src/tests). Tests can be run with pnpm test or pnpm db-test. If you only wish to run a specific test (i.e. you're actively writing code), you can run node /path/to/file.ts.

Further Reading

Please refer to the Discord documentation for further information on adding, using, and deleting slash commands. For more in-depth information, see the devloper documentation on application commands.

For Windows users using WSL, Microsoft has a tutorial for setting up a WSL development environment. They have put a lot of effort into making the integration of Windows, Linux, and VS Code seamless, so following their guide is the best advice. Docker and GPU acceleration are not required, but you can look into that if you wish.

The only VS Code extension not covered in the above guide is ESLint. To ensure your additions to the code are consistent with the existing rules, install the ESLint extension if you are contributing to development. Linters analyze your code for format errors and best practices. While not required, it is nice to have and ensures a consistent experience no matter who contributes to development. Remember that linters are a guide and can be too strict for your needs. Sometimes you need to overrule them.

Proper usage of these tools is beyond the scope of this wiki, but some common commands in git you will need are

git pull
git add .
git commit -m 'commit message goes here'
git push origin master
git stash
git stash pop