Add scripts/configure-guild.py

[NMertsch]

Summary

This script runs a Discord bot which will configure all connected guilds according to the provided configuration and then stops itself.

Benefits

This infrastructure-as-code approach has the following benefits compared to the current manual approach:

• Self-documenting
• Reproducible
• Avoid losing track of manual/ad-hoc changes
• Bot developers can trivially configure their own test server

Next Steps

At a later stage, we might want to create a GH Action to run this script with a single click.

Functionality

All updates are idempotent: If no update is required, no change is performed on the server.

Supported:

• Enable Community feature
• Configure roles
• Configure channel categories
  • Configure category permissions
• Configure text channels
  • Configure channel topic
  • Configure channel permissions
• Configure forum channels
  • Configure channel guidelines
  • Configure channel tags
    • Configure available tags
    • Make tags mandatory
  • Configure channel permissions
• Configure default messages
  • Allow links to channels and roles in channel topics/guidelines and default messages via <<#CHANNEL-NAME>> and <<@&ROLE-NAME>>

Most changes are non-destructive:

• Left untouched:
  • Unexpected categories
  • Unexpected channels
  • Unexpected tags
  • Unexpected roles
  • Existing permissions, unless they conflict with the new configuration
  • Existing messages created by non-bots
• Overwritten:
  • Category and channel positions
  • Channel topics and guidelines
  • "Mandatory/Optional" configuration for forum tags
  • Existing permissions, if they conflict with the new configuration
  • Existing messages created by bots, if default messages are configured for a channel, and all messages in that channel are created by bots

Testing

I tested the script on an empty, a semi-configured, and a fully configured server. The servers were configured as expected during the first execution, and no modifications were performed during the second execution.

About the implementation

Structure

The script has four parts:

1. Configuration model (pydantic.BaseModel subclass)
2. Configuration (model instance)
3. Configurator (plain Python class)
4. Infrastructure (Discord Bot and argparse program to execute the configuration)

Line Count

I know this is a long file. I considered two approaches to make it less daunting, but found both unsatisfactory.

1. Store the model instance in a .json or .toml file

I tested this, and found the .json and .toml files harder to understand and modify than the Python classes.

This is mainly for these:

• JSON does not support multi-line strings. Adding and modifying channel topics, guidelines, and default messages in a single line with \n characters is much more inconvenient compared to Python's multi-line strings.
• TOML supports indentation, but it is hard to read and discouraged by style guides. The Discord server configuration is a deeply nested structure, and TOML is not made for this.
• TOML supports arrays of tables, but without nesting it is hard to keep track of the overall structure.

We can revisit this later with minimal effort.

2. Split the code into multiple .py files

I tested this, and found that the effort did not outweigh the costs:

• Running a single-file Python program is easy: python file.py.
• Running a multi-file Python program either requires to be in the correct directory, to mess around with sys.path, or to create a package.

We can revisit this later. We will restructure the bot package in the next months anyway, and sub-apps like this one would fit in well.

[egeakman]

Hey @NMertsch! I think it overall looks great ❤️

[Optional] Maybe we can have the text definitions in a different file for long texts, what do you think?

[NMertsch]

@egeakman Thank you :)

After #205 is merged, I'd like to move this code into the main project and split it into multple files (model, configurator, bot, config).

I prefer to have all configuration for one thing (e.g. server setup) in one place. What would be the benefit of spreading the configuration across multiple files?

[NMertsch]

Force-merged without review to move forward with the Prod server.

If anyone has feedback or ideas, please don't hesitate to reach out! :)