Skip to content

armgit / wger

Public Imported from GitHub
0

Self hosted FLOSS fitness/workout, nutrition and weight tracker

Add AGENTS.md

Roland Geiderb155ba5a532c
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..b3e3b15b9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,153 @@
+# wger Django backend
+
+Django + DRF, dependency management via `uv`, lint/format via `ruff`. Tests use Django's built-in test runner. The
+React frontend (`../react`) and the Flutter app (`../flutter`) are clients of this server's REST API and PowerSync
+endpoints.
+
+## Verify after edits
+
+- `DJANGO_SETTINGS_MODULE=settings.ci uv run ./manage.py test wger.<app> --parallel auto`: scope to the app you changed,
+ the full suite is slow. `settings.ci` is what CI runs (SQLite, no migrations), always use it for tests.
+- `uv run ruff check wger/<path>`: lint
+- `uv run ruff format wger/<path>`: format
+- After model changes: `uv run ./manage.py makemigrations --check`
+
+Run the relevant ones for what you changed; comment- or docstring-only edits don't need a test run.
+
+For migrations: also test on a production-like DB copy when possible. Never run destructive migrations (`flush`, drop,
+schema reset) without asking.
+
+## Dev setup
+
+- `uv sync --group dev` installs everything. Never run `isort`: it was replaced by ruff and rewrites every import of the
+ file it touches. A stale copy may still sit in an old venv, `uv sync` removes it.
+- `wger-dev` in `.claude/launch.json` runs `manage.py runserver 8100` with `settings.local_dev` (SQLite, `DEBUG=True`).
+- Settings live in `settings/`, not inside `wger/`: `settings_global.py` (base), `local_dev.py`, `ci.py`, `main.py`
+ (production, configured via env vars). `settings/*_extra.py` is gitignored for local overrides.
+- `.mcp.json` configures the wger MCP server.
+
+## Layout
+
+```
+wger/<app>/
+├── models/ one file per model (or group), re-exported from models/__init__.py
+├── api/ DRF serializers, viewsets, filtersets
+├── views/ classic Django views (server-rendered pages, admin-ish forms)
+├── powersync.py upload handlers for the app's PowerSync-synced tables
+├── tasks.py Celery tasks
+├── signals.py cross-cutting post_save/post_delete handlers
+├── management/ management commands (syncs, maintenance)
+├── fixtures/ JSON fixtures, test-*.json for tests
+├── migrations/
+├── templates/
+└── tests/ test_*.py
+```
+
+| App | Purpose |
+|------------------|---------------------------------------------------------------------------------|
+| **manager** | Workout routines, sessions, logs, scheduling, weight/rep configs |
+| **exercises** | Exercise database (wiki-style), images, videos, muscles, categories, variations |
+| **nutrition** | Meal plans, ingredients, nutrition diary, Open Food Facts sync |
+| **core** | User profiles, languages, licenses, repetition units, weight units |
+| **measurements** | Body measurement categories and entries, incl. body weight |
+| **weight** | Compatibility surface for body weight, no models (see measurements) |
+| **gallery** | Progress photos |
+| **gym** | Gym/facility management |
+| **trophies** | Achievement system |
+| **mailer** | Email notification queue |
+| **utils** | Shared helpers, middleware, viewset/permission/pagination base classes |
+
+- All API endpoints live under `/api/v2/`, registered on a `DefaultRouter`. Auth: allauth headless + SimpleJWT, plus
+ legacy API tokens. Schema at `/api/v2/schema/ui` (drf-spectacular).
+- **Ownership:** user-owned models implement `get_owner_object()`; permission checks and the PowerSync upload
+ (`check_fk_ownership` in `wger/utils/viewsets.py`) rely on it. New user-owned models need it too.
+- `simple_history` tracks the exercise models; a field change there also changes the historical table in the migration.
+
+## Stack-specific rules
+
+- **The API schema is a contract.** Both clients and the generated python client are written against it. After a
+ serializer, filter or endpoint change, check whether `../react` and `../flutter` need the same change and say so.
+ `@action` endpoints need an explicit `@extend_schema(responses=...)`, otherwise the schema shows the wrong shape.
+- **API changes bump the dev version:** if a change touches the REST API in any meaningful way (new or changed endpoint,
+ field, accepted value, validation or response shape), increment the `dev.N` suffix of `VERSION_STRING` in
+ `wger/version.py` in the same change, e.g. `2.8.0-dev.0` to `2.8.0-dev.1`. Clients can then tell which dev build has
+ the feature. Keep the semver form `-dev.N` (see the docstring there). Small changes (a different validation error,
+ etc.) can stay, when in doubt just ask.
+- **PowerSync:** clients read synced tables from a local copy and write them back through `wger/<app>/powersync.py`.
+ A new field or table on a synced model needs the sync rules in the docker repo
+ (`../docker/services/config-powersync/sync_rules.yaml`) and the upload handler updated. Rows that already exist on a
+ device keep NULL for a new column until they are downloaded again, so either backfill in a data migration (touching
+ the rows) or keep the column nullable/defaulted on the client side (see the flutter AGENTS.md).
+- **Dates and time zones:** `USE_TZ = True`, `TIME_ZONE = 'UTC'`; store instants as aware datetimes
+ (`django.utils.timezone`), never naive ones. "Which calendar day" questions use the owner's
+ `UserProfile.timezone`, not the zone of the request; empty means unknown. Use `DateField` for calendar days and
+ `DateTimeField` for instants, the clients map them differently.
+- **Malformed IDs:** serializers and django-filter already answer bad IDs with 400. Manual lookups in viewsets or
+ filters (`int(request.GET[...])`, `UUID(...)`) need a guard, otherwise they end up as 500.
+- **Celery:** production runs with Celery, but `USE_CELERY=False` is supported, so a task must also work when called
+ inline.
+- **i18n:** user-visible strings go through `gettext`/`{% translate %}`. Translations come from Weblate, don't edit the
+ `.po` files of other languages. If a client already has the string, reuse its English text exactly.
+- **Logs:** never log secrets at any level (tokens, passwords, auth response bodies).
+- **Secrets / debug flags:** never commit a real `SECRET_KEY` or leave `DEBUG=True` in non-test config.
+- **Install/config changes:** new env vars, settings or docker changes also need the documentation in `../docs`
+ (readthedocs) updated.
+
+## Migration & data changes
+
+- **Existing bad data:** schema changes that add NOT NULL or unique constraints must include a data migration that fixes
+ existing rows, not just the schema. Never assume the table is clean.
+- **Unreleased migrations:** if a migration was added on the current branch / since the last release, edit it instead of
+ stacking a new one on top, then verify with `makemigrations --check`.
+- **Callable defaults:** `default=uuid.uuid4`, `default=timezone.now`, never `default=uuid.uuid4()` (evaluated once at
+ import time). Same rule for any default that produces a fresh value.
+- **Unique constraints:** if a model has a unique constraint, audit *every* call site that creates an instance
+ (`grep -rn "ModelName.objects.create\|ModelName(" --include="*.py"`). All sites should use `update_or_create` /
+ `get_or_create`. Don't fix only the failing one.
+- **Triggers / signals:** when adding `post_save` handlers or DB triggers, walk through one example transaction and check
+ ordering / recursion before declaring done.
+
+## Tests
+
+- **Base classes:** `WgerTestCase`, `WgerAddTestCase`, `WgerEditTestCase`, `WgerDeleteTestCase`, `WgerAccessTestCase`
+ in `wger/core/tests/base_testcase.py`; `ApiBaseResourceTestCase` and the `Api*TestCase` mixins in
+ `wger/core/tests/api_base_test.py`. Use them, and the `test-*.json` fixtures, instead of building setup by hand.
+- **Cross-cutting API tests as mixins:** wire a new behavior check into the existing per-model `*CustomApiTestCase`
+ via a mixin instead of duplicating URLs and payloads in a new class.
+- **Bug fixes need regression tests** that fail on the old code and pass on the new.
+- **Prove a test can fail.** After writing one, break the production side it guards and watch it go red, then restore.
+- **URLs via `reverse('namespace:name')`**, not hard-coded `/api/v2/...` strings.
+- **Don't test library behavior.** No tests that only exercise DRF or django-filter defaults; test custom methods and
+ overrides.
+- **Dates:** timezone-aware datetimes only. Test the boundary days of a date range (start day, end day, the day after)
+ and ranges across a DST switch, which has 23 or 25 hours.
+- **No hard-coded PKs** in test data; SQLite and Postgres assign them differently, also with `bulk_create`.
+- **Mock at the usage site** (`wger.app.module.name`), not where the name is defined.
+- **Docstrings state what is verified**, no bug history ("Regression: ...") and no justification for the test's
+ existence.
+
+## Code style
+
+- Line length 100, single quotes, formatter `ruff format`.
+- Imports sorted by ruff's isort rules (`I`), section order `FUTURE → STDLIB → DJANGO → THIRDPARTY → FIRSTPARTY →
+ LOCAL`, each with a heading comment. The `I` rule is off for migrations, `settings/`, `extras/` and `apps.py`. Ruff
+ never explodes an import into one name per line by itself but keeps an existing magic trailing comma; write new
+ multi-name imports in that exploded style by hand.
+- Comments and docstrings in English and short: one line where one does, comment only what the code can't express. The
+ derivation belongs in the commit message or the test. No em-dashes, use a period, colon or parentheses.
+- Type hints on new helpers with plain types; skip them where they would need generics, `TypeVar` or `Protocol`.
+
+## Other rules
+
+- **Visible changes go into CHANGELOG.md:** if a feature, behavior change or bug fix is noticeable for users,
+ self-hosters or API clients, add a short entry to the matching section of `CHANGELOG.md` in the same change.
+ Internal refactors and small fixes don't need one, when in doubt just ask.
+- **No advisory IDs** (GHSA etc.) in code, comments or commit messages.
+
+## Scope
+
+Make the minimum change requested. Don't refactor adjacent code, rename things, or change defaults unless explicitly
+asked. Mention adjacent issues as follow-ups instead of fixing them inline.
+
+When programming for special cases, either ask or check first how probable they are (rare race conditions, parallel
+usage of the app with different devices, etc.).