50 lines
4.4 KiB
Markdown
50 lines
4.4 KiB
Markdown
Use the version of Python/Pytest in the .venv directory when attempting to run commands, as that's where the pip dependencies (and pytest) are installed.
|
|
|
|
## Database migrations
|
|
|
|
Schema changes use Alembic (migrations live in `src/pirats/migrations/`, shipped inside the package). The app applies them automatically at startup via `pirats.database.run_migrations()`; databases predating Alembic are normalized and stamped at the `0001` baseline first.
|
|
|
|
After editing `src/pirats/models.py`, generate a migration and sanity-check it:
|
|
|
|
```
|
|
.venv/bin/alembic revision --autogenerate -m "describe the change"
|
|
.venv/bin/alembic upgrade head # or just start the app
|
|
```
|
|
|
|
**Note on adding NOT NULL columns in SQLite:**
|
|
SQLite does not support adding a `NOT NULL` column without a default value to an existing table. When Alembic auto-generates a migration that adds a `nullable=False` column, you MUST manually edit the migration to include `server_default="..."` in the `sa.Column` definition (e.g., `server_default=""` for strings) before applying it. Otherwise, the migration will crash with `Cannot add a NOT NULL column with default value NULL`.
|
|
|
|
Do NOT add ad-hoc `ALTER TABLE` statements to `database.py` — that legacy list exists only to upgrade pre-Alembic databases to the baseline and must not grow.
|
|
|
|
## Visual verification
|
|
|
|
Always visually verify fixes or changes expected to have an aesthetic impact in the running app before marking them complete. Inspect browser screenshots of the affected UI, including relevant interaction states (such as expanded and collapsed panels) and screen sizes when layout is affected. Code review, DOM inspection, automated tests, and a successful build do not replace visual verification. Correct any visual issues found and inspect the result again. If visual verification is blocked, explicitly report the blocker and do not claim the appearance is verified.
|
|
|
|
## Learning during testing
|
|
|
|
When you run into a repeatable problem during testing (e.g. port assignment collision, missing executable, etc), note down the problem and solution in this file so that you'll have access to it in future sessions.
|
|
|
|
- If Alembic autogeneration says the target database is not up to date, create a temporary database with `DATABASE_URL=sqlite:////tmp/<name>.db .venv/bin/alembic upgrade head`, then run the autogeneration command with that same `DATABASE_URL`.
|
|
|
|
- Before browser testing, check whether the default Vite port belongs to this project. If it is occupied by another app, start this frontend with `npm --prefix frontend run dev -- --host 127.0.0.1 --port 5174 --strictPort` and use that URL. Local server binds may require sandbox escalation.
|
|
|
|
- In-memory SQLite tests that use FastAPI TestClient need `poolclass=StaticPool` as well as `check_same_thread=False`, so request threads share the database after commits. Otherwise they can fail with `no such table`.
|
|
|
|
- Rollback tests must fetch Player/Obstacle/Challenge/Vote rows again by ID after `apply_game_state`; it deletes and recreates those rows, so old ORM instances cannot be refreshed.
|
|
|
|
- The project `.venv` uses Python 3.9. Use `Optional[T]` (or postponed annotations) instead of evaluated `T | None` annotations, which fail during import.
|
|
|
|
- Multi-socket TestClient tests must use `with TestClient(app) as client` so sockets share one event loop; separate portals can hang on cross-socket broadcasts. Close sockets explicitly before asserting disconnect messages. Override lifespan when using an isolated test database.
|
|
|
|
## Versioning & changelog
|
|
|
|
The app shows its version number and a player-facing changelog in the ☰ menu → About. Both come from `frontend/src/lib/changelog.js` (rendered by `frontend/src/components/AboutModal.svelte`).
|
|
|
|
- Bump `VERSION` by one on **every** commit.
|
|
- When a commit changes something players can see, add an entry to the **top** of `CHANGELOG` (`{ version, date, changes: [...] }`) describing it in player-facing terms. Group everything shipping under one version into a single entry.
|
|
- The changelog is for players: skip refactors, tests, tooling, and other internal-only changes. A commit with no user-facing change bumps `VERSION` but adds no entry.
|
|
|
|
## Work order
|
|
|
|
You will be working on tasks in [TODO.md](./TODO.md]. Work on at most two tasks at a time (one is preferable, but two is fine if they dove tail really nicely), and after you finish each task, make a git commit and update the TODO list to check off the completed task.
|