ryg/royalnet
ryg/royalnet
1
Fork 0
mirror of https://github.com/RYGhub/royalnet.git synced 2024-10-16 06:27:27 +00:00
Code Activity

Create a CONTRIBUTING document

Browse source
This commit is contained in:
Steffo 2024-08-19 06:48:20 +02:00
parent 067f4d5414
commit 42636650ac
Signed by: steffo
GPG key ID: 5ADA3868646C3FC0
3 changed files with 292 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
.example.env Normal file
View file

@ -0,0 +1,15 @@
export DATABASE_AUTOMIGRATE='true'
export DATABASE_URL='postgres:///royalnet?host=/run/postgresql/'
export TELEGRAM_DATABASE_URL='postgres:///royalnet?host=/run/postgresql/'
export TELEGRAM_BOT_TOKEN='1234567890:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'
export TELEGRAM_NOTIFICATION_CHATID='-1001899805480'
export BROOCH_DATABASE_URL='postgres:///royalnet?host=/run/postgresql/'
export BROOCH_GRAPHQL_URL='https://api.stratz.com/graphql'
export BROOCH_STRATZ_TOKEN='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
export BROOCH_TELEGRAM_BOT_TOKEN='1234567890:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'
export BROOCH_WATCHED_GUILD_ID='9257'
export BROOCH_MIN_PLAYERS_TO_PROCESS='1'
export BROOCH_NOTIFICATION_CHAT_ID='-1001234567890'
export BROOCH_MAX_IMP_WAIT_SECS='3600'

277
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,277 @@
# 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.
[Rust]: https://www.rust-lang.org/
#### On Linux
1. Download `rustup` from your distribution's package manager:
```shell
# On Arch Linux
pacman -Syu rustup
```
2. Use `rustup` to install the latest stable toolchain:
```shell
rustup default stable
```
#### On Windows
1. Follow the instructions at the [Install Rust] page.
2. Use `rustup` to install the latest stable toolchain:
```shell
rustup default stable
```
[Install Rust]: https://www.rust-lang.org/tools/install
### 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.
[RustRover]: https://www.jetbrains.com/rust/
[Jetbrains]: https://www.jetbrains.com/
[Steffula Ultra]: https://plugins.jetbrains.com/plugin/22749-steffulaultra-color-scheme
### 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:
```shell
# 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.
[Git download page]: https://git-scm.com/downloads
### 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:
```shell
# 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:
```shell
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
[conditional compilation]: https://doc.rust-lang.org/reference/conditional-compilation.html
[Cargo features]: https://doc.rust-lang.org/cargo/reference/features.html
#### On RustRover
If you're editing the project with RustRover, you can graphically toggle features on and off:
1. Open `Cargo.toml`.
2. Scroll to the `[features]` section
3. Tick or untick the features you want to use.
- `default` is ignored if you use the provided run configurations.
#### Elsewhere
To toggle features on other editors, remember to pass the `--no-default-features` and `--features` option to Cargo when running commands:
```shell
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:
```shell
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:
```shell
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:
```url
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:
```dotenv
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:
```shell
cargo install cargo-binstall
```
7. Binstall [diesel_cli] to allow `cargo` to perform operations on the database:
```shell
cargo binstall diesel_cli
```
8. Load the `.env` file into your current environment:
```shell
source .env
```
9. Generate the database schema by running all migrations with `diesel_cli`:
```shell
~/.cargo/bin/diesel_cli migration run
```
[PostgreSQL]: https://www.postgresql.org/
[connection URI]: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
[cargo-binstall]: https://crates.io/crates/cargo-binstall
### 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:
```dotenv
export BROOCH_STRATZ_TOKEN='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
```
[STRATZ]: https://stratz.com/
[GraphQL API]: https://api.stratz.com/graphiql/
[Dota 2]: https://store.steampowered.com/app/570/Dota_2/
[Steam]: https://steamcommunity.com/
[My Tokens]: https://stratz.com/api
### 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:
```dotenv
# Assuming the copied chat id is `123456789`
export TELEGRAM_NOTIFICATION_CHATID='-100123456789'
export BROOCH_NOTIFICATION_CHAT_ID='-100123456789'
```
[Telegram Desktop]: https://desktop.telegram.org/
[bot]: https://core.telegram.org/bots
[official client]: https://telegram.org/apps
## 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:
```shell
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:
```shell
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:
```shell
source .env
cargo doc --open
```

11
README.md
View file

@ -8,17 +8,6 @@ Fun software suite for the RYG community
</div>
## 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.
## Quotes
> I can't believe I'm doing this again.