chore: update readme, example config, and running documentation

Co-authored-by: asleepyskye <skye@vixen.lgbt>

dev-docs/BRANCHRENAME.md

@@ -0,0 +1,18 @@
+On 2020-06-22, we renamed the `master` branch to `main`. 
+
+This should mean very little, but if you have existing clones,
+you'll need to update the branch references, like so:
+
+1. **Fetch the latest branches from the remote:**  
+`$ git fetch --all`
+2. **Update the upstream remote's HEAD**  
+`$ git remote set-head origin -a`
+3. **Switch your local branch to track the new remote**  
+`$ git branch --set-upstream-to origin/main`
+4. **Rename your branch locally**  
+`$ git branch -m master main`
+
+(steps from https://dev.to/rhymu8354/git-renaming-the-master-branch-137b)
+
+The `master` branch was fully deleted on 2020-07-28.
+If you get an error on pull on an old clone, that's why. The commands above should still work, though.

dev-docs/LEGACYMIGRATE.md

@@ -0,0 +1,37 @@
+# Legacy bot migration
+Until the introduction of the database migration system around December 2019, migrations were done manually.
+
+To bridge the gap between the `legacy` branch's database schema and something the modern migration system can work with, run the following SQL commands on the database:
+
+```sql
+-- Create the proxy_tag type
+do $$ begin
+    create type proxy_tag as (
+        prefix text,
+        suffix text
+    );
+exception when duplicate_object then null;
+end $$;
+
+-- Add new columns to `members`
+alter table members add column IF NOT EXISTS display_name text;
+alter table members add column IF NOT EXISTS proxy_tags proxy_tag[] not null default array[]::proxy_tag[];
+alter table members add column IF NOT EXISTS keep_proxy bool not null default false;
+
+-- Transfer member proxy tags from the `prefix` and `suffix` columns to the `proxy_tags` array
+update members set proxy_tags = array[(members.prefix, members.suffix)]::proxy_tag[]
+    where members.prefix is not null or members.suffix is not null;
+
+-- Add other columns
+alter table messages add column IF NOT EXISTS original_mid bigint;
+alter table servers add column IF NOT EXISTS log_blacklist bigint[] not null default array[]::bigint[];
+alter table servers add column IF NOT EXISTS blacklist bigint[] not null default array[]::bigint[];
+
+-- Drop old proxy tag columns
+alter table members drop column IF EXISTS prefix cascade;
+alter table members drop column IF EXISTS suffix cascade;
+```
+
+You should probably take a database backup before doing any of this.
+
+The .NET version of the bot should pick up on any further migrations from this point :) 

dev-docs/README.md

@@ -0,0 +1,21 @@
+# PluralKit development documentation
+
+Most of PluralKit's code is written in C#, and is split into 3 projects: `PluralKit.Core` (supporting libraries), `PluralKit.Bot` (the Discord bot), and `PluralKit.API` (ASP.NET webserver with controllers for most API endpoints).
+
+There is an ongoing effort to port this code to Rust, and we have a handful of crates already. Currently, the main Rust services are `gateway` (connects to Discord to receive events), `api` (handles authentication and rate-limiting for the public API, as well as a couple of private endpoints), and `scheduled_tasks` (background cron job runner, for statistics and miscellaneous cleanup).
+
+At the very least, `PluralKit.Bot` and `gateway` are required for the bot to run. While code still exists to connect to the Discord gateway directly from the C# bot, this is no longer a supported configuration and may break in the future.
+
+Service-specific documentation can be found for the C# services in [dotnet.md](./dotnet.md), and for the Rust services in [rust.md](./rust.md) (todo; there is a temporary mostly-accurate document at [RUNNING.md](./RUNNING.md)).
+
+## Building/running
+
+PluralKit uses a PostgreSQL database and a Redis database to store data. User-provided data is stored in Postgres; Redis is used for internal state and transient data such as the command execution cache. It's generally easy to run these in Docker or with the Nix `process-compose`, but any install method should work.
+
+The production instance of PluralKit uses Docker images built in CI. These take a long time to rebuild and aren't good for development (they're production builds, so it's not possible to hook up a debugger). Instead, it's preferable to install build dependencies locally. This is easy with the provided Nix flake: run `nix develop .#bot` to drop into a shell with all the C# build dependencies available, and `nix develop .#services` to get a shell with the Rust build dependencies. It's also okay to manually install build dependencies if you prefer.
+
+PluralKit services are configured with environment variables; see service-specific documentation for details. Generally, the configuration from the self-host `docker-compose.yml` should get you started.
+
+## Upgrading database from legacy version
+If you have an instance of the Python version of the bot (from the `legacy` branch), you may need to take extra database migration steps.
+For more information, see [LEGACYMIGRATE.md](./LEGACYMIGRATE.md).

dev-docs/RUNNING.md

@@ -0,0 +1,69 @@
+# Technical Overview:
+
+PluralKit is composed of several different parts, some of which optional and not needed for the bot to function in a testing environment.
+##### Required:
+- Bot (*PluralKit.Bot*)
+- Gateway
+- PostgreSQL Database
+- Redis Database
+##### Optional:
+- API (*PluralKit.API*)
+- Scheduled Tasks (*scheduled_tasks*)
+
+*Optionally, it can also integrate with Sentry for error reporting, and InfluxDB for aggregate statistics. In production, we use [VictoriaMetrics](https://victoriametrics.com/) InfluxDB competible endpoint, to query metrics in a Prometheus-compatible format.
+
+The bot and API are built using .NET 8, with other optional components used for scaling (ex. scheduled_tasks) built using Rust.
+# Building + Running
+
+**The below procedures are intended for development and testing use only!
+
+Newer versions of the bot have moved to using [Nix](https://nixos.org/) for simplified builds. A docker compose file is also provided, but not recommended as it is not actively maintained.
+
+See [Configuration](./CONFIGURATION.md) for full details on configuration as only the basics will be covered here.
+Configuration is done through a JSON configuration file `pluralkit.conf` placed in the bot's working directory. An example of the configuration format can be seen in [pluralkit.conf.example](pluralkit.conf.example).
+The minimum configuration needed for the bot to function must include the following:
+- **`PluralKit.Bot.Token`**: the Discord bot token to connect with
+- **`PluralKit.Bot.ClientId`**: the ID of the bot's user account, used for calculating the bot's own permissions and for the link in `pk;invite`
+- **`PluralKit.Database`**: the URI of the PostgreSQL database to connect to (in [ADO.NET Npgsql format](https://www.connectionstrings.com/npgsql/))
+- **`PluralKit.RedisAddr`**: the `host:port` of the Redis database to connect to
+
+**When running using Docker, you do not need to specify the Postgres or Redis URLs as these will be overwritten by environment variables in the compose file.**
+
+**When using Nix, the Database URI Username, Password, and Database fields must match what the database was setup with in the `flake.nix` file!**
+
+The bot can also take configuration from environment variables, which will override the values read from the file. Here, use `:` (colon) or `__` (double underscore) as a level separator (eg. `export PluralKit__Bot__Token=foobar123`) as per [ASP.NET config](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1#environment-variables).
+## Nix (recommended)
+The bot, databases, and services are available to run all in one as a Nix flake (using process-compose-flake). 
+As of the writing of this document, there are a few caveats with the current flake file.
+- The database URI in the config must match the username, password, and database specified during database creation (currently `postgres`, `postgres`, and `pluralkit` respectively).
+- Not all services are added to the flake file yet.
+
+**Additionally, as of the writing of this document, the `pluralkit-gateway` service reads environment variables to get the bot token and database URLs, so you also need to create a `.env` file in the `PluralKit` directory with the following variables:**
+```
+pluralkit__db__db_password="postgres"
+pluralkit__db__data_db_uri="postgresql://postgres@localhost:5432/pluralkit"
+pluralkit__db__data_redis_addr="redis://localhost:6379"
+pluralkit__discord__bot_token="BOT_TOKEN_GOES_HERE"
+pluralkit__discord__client_id="BOT_CLIENT_ID_GOES_HERE"
+pluralkit__discord__client_secret=1
+pluralkit__discord__max_concurrency=1
+```
+**(This should match the username/password/database specified in the flake file and the configuration file)**
+
+*(assuming you already have Git installed, if not, you can start a shell with git by running `nix-shell -p git`)*
+1. Clone the repository: `git clone https://github.com/PluralKit/PluralKit`
+2. Create a `pluralkit.conf` configuration file in the `PluralKit` directory
+	- Again, the DB URI parameters must match what's in the `flake.nix` file
+3. Create a `.env` configuration file in the `PluralKit` directory *(see above)*
+4. Build and run: `nix run .#dev`
+	- This will download the dependencies, build, and run PluralKit
+	- If Nix is not setup to allow flakes, you may need to add `--extra-experimental-features nix-command --extra-experimental-features flakes` to the command
+	- If the `pluralkit-bot` process fails to run, you can restart it by selecting it and pressing `Ctrl-R`
+```
+[nix-shell:~]$ git clone https://github.com/PluralKit/PluralKit
+[nix-shell:~]$ cd PluralKit
+[nix-shell:~/PluralKit]$ cp pluralkit.conf.example pluralkit.conf
+[nix-shell:~/PluralKit]$ nano pluralkit.conf
+[nix-shell:~/PluralKit]$ nano .env
+[nix-shell:~/PluralKit]$ nix run .#dev
+```