royalnet/CONTRIBUTING.md

Contributor's guide

Branches and tags

The main branch represents the current state of the bot.

New features are developed on feature/* branches for the development of specific features; these are to be squashed as a single commit onto the main branch.

Pushing a v* tag will automatically trigger the build of a new Docker image for the tagged commit.
Please use annotated tags (git tag -a) if possible!

Old Royalnet versions are available for reference on the historic/*/* orphan branches.

Setting up a development environment

Follow these instructions to setup a Royalnet development environment, so that you may be able to test your changes!

Installing Rust

You'll need to have the latest stable version of the Rust toolchain installed.

On Linux

1. Download rustup from your distribution's package manager:

   # On Arch Linux
   pacman -Syu rustup
   

2. Use rustup to install the latest stable toolchain:

   rustup default stable   
   

On Windows

1. Follow the instructions at the Install Rust page.
2. Use rustup to install the latest stable toolchain:

   rustup default stable   
   

Installing an IDE

Using an IDE for Rust is highly recommended!

Steffo's personal recommendation is RustRover by Jetbrains with the Steffula Ultra color scheme, which provides a fully visual environment for interacting with the Rust toolchain.

Installing Git

To contribute changes to the project, you need to have the [Git] version control system installed.

On Linux

It's very likely that git is bundled with your Linux distribution.

In case it isn't:

1. Download it from your distribution's package manager:

   # On Arch Linux
   pacman -Syu git
   

On Windows

Windows doesn't bundle git, so you'll need to download and install it externally.

1. Download it from the Git download page.
2. Install it by running the downloaded executable.
   • The default options provided by the installer are fine, but you might want to change the one allowing you to pick the text editor to use with git to match the one you're most comfortable with.

Configuring Git

If you have never used Git before on your machine, you have to configure your identity before you're able to create new commits:

# This will be publicly visible, if you're uncomfortable with that, you may use a pseudonym.
git config --global user.name "Name Surname"
# This needs to be the same email you've used to sign up to GitHub!
git config --global user.email "example@example.org"

Creating a configuration file

To configure the bot's features with parameters whose value has to remain secret, an .env file in the root directory of the project is used.

An example file .example.env is provided with the repository; copy it to .env to make use of it as a template:

cp .example.env .env

Selecting features

To minimize compilation times and configuration work needed, Royalnet supports conditional compilation via Cargo features.

The following features are currently available:

• interface_database
  • allows interaction with a PostgreSQL database
• interface_stratz
  • allows interaction with the STRATZ GraphQL API
• service_telegram
  • processes commands sent to a [Telegram] bot
• service_brooch
  • sends notifications to a [Telegram] group about recently played Dota 2 matches via a bot
• default
  • includes all features

To toggle features on other editors, remember to pass the --no-default-features and --features option to Cargo when running commands:

cargo --no-default-features --features="interface_database,interface_stratz,service_telegram,service_brooch" run

Configuring PostgreSQL

Note

You'll need to configure PostgreSQL only if you're developing something using the interface_database feature.

Royalnet stores some persistent data inside a PostgreSQL database, so you might need one installed to test things that use it:

1. Make sure you have an instance of the DBMS available to use somewhere reachable from your machine.
2. Create an user to use with royalnet.
   • If you're on a Linux system, and you have installed PostgreSQL via your package manager, most likely you'll be able to create an usable user with:

     sudo --user=postgres -- createuser "$USER"
     

3. Create a database
   • If you're on a Linux system, and you have installed PostgreSQL via your package manager, most likely you'll be able to create an usable database with:

     sudo --user=postgres -- createdb --owner="$USER" royalnet
     

4. Use the connection URI documentation page to determine the string to use to access your database:
   • If you're on a Linux system, and you have installed PostgreSQL via your package manager, most likely the connection string will be:

     postgres:///royalnet?host=/run/postgresql/
     

5. Set the DATABASE_URL, TELEGRAM_DATABASE_URL and BROOCH_DATABASE_URL variables in the .env file to the connection URI:

   export DATABASE_URL='postgres:///royalnet?host=/run/postgresql/'
   export TELEGRAM_DATABASE_URL='postgres:///royalnet?host=/run/postgresql/'
   export BROOCH_DATABASE_URL='postgres:///royalnet?host=/run/postgresql/'
   

6. Install cargo-binstall to allow cargo to download pre-compiled executables:

   cargo install cargo-binstall
   

7. Binstall [diesel_cli] to allow cargo to perform operations on the database:

   cargo binstall diesel_cli
   

8. Load the .env file into your current environment:

   source .env
   

9. Generate the database schema by running all migrations with diesel_cli:

   ~/.cargo/bin/diesel_cli migration run
   

Configuring the STRATZ GraphQL API

Note

You'll need to configure the STRATZ GraphQL API only if you're developing something using the interface_stratz feature.

Royalnet uses the STRATZ GraphQL API to retrieve information about past Dota 2 matches, so you might need to configure it to make some data available:

1. Log in to STRATZ with your Steam account.
2. Visit the My Tokens page.
3. Click the "Show Token Information" button.
4. Copy the displayed token.
5. Set the BROOCH_STRATZ_TOKEN variable in your .env to the token you've just copied:

   export BROOCH_STRATZ_TOKEN='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
   

Configuring a Telegram bot

Note

You'll need to configure a Telegram bot for commands only if you're developing something using the service_telegram or service_brooch features.

Royalnet can be interacted with via a [Telegram] bot, a special user account that allows for automated interactions with chat rooms, which needs to be manually created:

1. Log in to Telegram using Telegram Desktop.
2. Search for the account with the username @BotFather.
3. Send the /start command.
4. Send the /newbot command.
5. Answer the questions asked by the BotFather.
6. Once the bot is created, copy the displayed token.
7. Set the TELEGRAM_BOT_TOKEN and BROOCH_TELEGRAM_BOT_TOKEN variables in your .env to the token you've just copied.
8. Open Telegram Desktop's "Settings" modal.
9. Navigate to the "Advanced" category.
10. Navigate to the "Experimental settings" subcategory.
11. Enable the "Show Peer IDs in Profile" option.
12. Close the modal.
13. Create a new group containing just you and the bot you've just created.
14. Open the "Manage group" menu.
15. Navigate to the "Administrators" category.
16. Click on your profile.
17. Enter anything in the "Custom title" field.
18. Click "Save" two times.
19. Close the modal.
20. Click the group's name on the top of the window.
21. Click on the group's id to copy it.
22. Set the TELEGRAM_NOTIFICATION_CHATID and BROOCH_NOTIFICATION_CHAT_ID variables in your .env to -100, followed by the ID you've just copied:

    # Assuming the copied chat id is `123456789`
    export TELEGRAM_NOTIFICATION_CHATID='-100123456789'
    export BROOCH_NOTIFICATION_CHAT_ID='-100123456789'
    

Using the development environment

The following recipes are available to perform most frequently used actions.

Run Royalnet

The Run run configuration or the following script runs Royalnet with all the enabled features:

source .env
cargo run

Check the validity and quality of the code

The Clippy run configuration or the following script checks the whole source code for errors, warnings, anti-patterns and potential mistakes:

source .env
cargo clippy

Open documentation

The Doc run configuration or the following script compiles the documentation of all available crates, then opens it in your web browser:

source .env
cargo doc --open