
[![Build status](https://img.shields.io/github/actions/workflow/status/TheMotte/rDrama/test.yml?branch=frost)](https://github.com/TheMotte/rDrama/actions?query=workflow%3AE2ETests+branch%3Afrost)

This code runs https://www.themotte.org .

Join [the Dev Discord](https://discord.gg/KChpcdaNJC) for help.

# Installation (Windows/Linux/MacOS)

1 - Install [a container runtime and the Docker commandline tools](https://docs.docker.com/get-docker/) on your machine.

On Windows, Docker will pester you to pay them money for licensing. If you want something less proprietary, consider [Container Desktop](https://container-desktop.io) or [Stevedore](http://github.com/slonopotamus/stevedore) instead.

2 - Install [Git](https://git-scm.com/). If you're on Windows and want a GUI, [Github Desktop](https://desktop.github.com/) is quite nice.

3 - Run the following commands in the terminal or command line for first-time setup:

```sh
git clone https://github.com/themotte/rDrama/

cd rDrama
```

4 - Run the following command to start the site:

```sh
docker compose up --build
```

The first time you do this, it will take a while. It'll be (much) faster next time.

4 - Visit `localhost` in your browser.

5 - Make an account. The first account made will have admin power.

6 - That's it!

Most code edits will be reflected (almost) immediately. If you make any setup changes or database changes, you'll need to ctrl-C the docker status log and run `docker compose up --build` again.

Chat-related code edits will take a minute to update (if it's in Python) or won't be reflected automatically at all (if it's in React). Improvements welcome! But almost nobody touches these systems, so it hasn't been a priority.

# Run the E2E tests:

`./util/test.py`

# Database Stuff

## What is a migration?

Prior to the fork of themotte from rDrama, there were no database migrations, and the database schema was stored in `schema.sql`. Any time a column or such was added to a model, one hoped that the author remembered to update `schema.sql` to add that column. One of the first changes we made after forking this repo was to add database migrations using Alembic.

Database migrations are instructions for how to convert an out-of-date database into an up-to-date database. This can involve changing the schema, or changing data within the database.

## Why use database migrations

Database migrations allow us to specify where data moves when there are schema changes. This is important when we're live -- if we rename the `comments.ban_reason` column to `comments.reason_banned` for naming consistency or whatever, and we do this by dropping the `ban_reason` column and adding a `reason_banned` column, we will lose all user data in that column. We don't want to do this. With migrations, we could instead specify that the operation in question should be a column rename, or, if the database engine does not support renaming columns, that we should do a three-step process of "add new column, migrate data over, drop old column".

## Database schema change workflow

As an example, let's say we want to add a column `is_flagged` to the `comments` table.

1. Update the `Comment` model in `files/classes/comment.py`
```python
	from files.classes.base import Base
	class Comment(Base):
		__tablename__ = "comments"
		id = Column(Integer, primary_key=True)
		...
+		is_flagged = Column(Boolean, default=False, nullable=False)
```

2. Autogenerate a migration with a descriptive message. To do this, run
```sh
./util/command.py db revision --autogenerate --message="add is_flagged field to comments"
```

This will create a migration in the `migrations/versions` directory with a name like `migrations/versions/2022_05_23_05_38_40_9c27db0b3918_add_is_flagged_field_to_comments.py` and content like
```python
"""add is_flagged field to comments
Revision ID: 9c27db0b3918
Revises: 16d6335dd9a3
Create Date: 2022-05-23 05:38:40.398762+00:00
"""
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision = '9c27db0b3918'
down_revision = '16d6335dd9a3'
branch_labels = None
depends_on = None
def upgrade():
    op.add_column('comments', sa.Column('is_flagged', sa.Boolean(), nullable=False))
def downgrade():
    op.drop_column('comments', 'is_flagged')
```

3. Examine the autogenerated migration to make sure that everything looks right (it adds the column you expected it to add and nothing else, all constraints are named, etc.) If you see a `None` in one of the alembic operations, e.g. `op.create_foreign_key_something(None, 'usernotes', 'users', ['author_id'])`, please replace it with a descriptive string before you commit the migration.

4. Restart the Docker container to make sure it works.

```sh
docker compose up --build
```

## So what's up with original-schema.sql, can I just change that?

No, please do not do that. Instead, please make a migration as described above.
