jeanGaston
4c5a926227
Codifies the dev/main branching model and secret-handling rules being introduced alongside the upcoming container/web GUI work, so future changes (by humans or agents) stay consistent. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
68 lines
3.4 KiB
Markdown
68 lines
3.4 KiB
Markdown
# Agent instructions for this repository
|
|
|
|
This file guides both human contributors and AI coding agents working in this
|
|
repo. Follow it unless the user explicitly asks for something different.
|
|
|
|
## Branching model
|
|
|
|
- `main` — always deployable. Only receives finished, working changes.
|
|
- `dev` — integration branch for in-progress work (new features, larger
|
|
refactors, anything not yet proven). Merge to `main` only once it works.
|
|
- Feature branches (optional): `feature/<short-name>` or `fix/<short-name>`
|
|
cut from `dev` for anything that touches multiple files or takes more than
|
|
one sitting. Small, obvious fixes can go straight to `dev`.
|
|
|
|
Rebase feature branches on `dev` before opening a PR/merge if `dev` has moved
|
|
on; don't merge `dev` into `main` with unresolved conflicts.
|
|
|
|
## Commit practices
|
|
|
|
- Commit early and often — one logical change per commit. Don't bundle an
|
|
unrelated refactor with a bug fix.
|
|
- Write commit messages in the imperative mood ("Add exclusion support", not
|
|
"Added" or "Adding"), with a short summary line (~50-70 chars) and, if
|
|
needed, a blank line followed by bullet points explaining *why*.
|
|
- Never commit secrets: SMTP credentials, real participant CSV paths, API
|
|
keys. Real configuration lives in a local `.env` file (gitignored) —
|
|
`env.py` only reads `os.environ`/`.env` and must never hardcode real values.
|
|
If you add a new secret, add its placeholder to `.env.example` too.
|
|
- Before committing, check `git status` and `git diff` for anything
|
|
unexpected (stray debug prints, personal file paths, credentials).
|
|
- Prefer creating new commits over amending, unless explicitly asked to amend
|
|
and the previous commit hasn't been pushed/shared.
|
|
- Don't use `--no-verify`, force-push, or rewrite shared history without
|
|
explicit user approval.
|
|
- Run whatever tests/scripts are relevant before committing (`src/test_draws.py`
|
|
for conflict checks; manually exercise `main.run_draw()` or the web GUI for
|
|
behavior changes — there's no CI yet).
|
|
|
|
## Code style
|
|
|
|
- Keep the existing flat-module layout in `src/` (`draw.py`, `file_io.py`,
|
|
`emailer.py`, `env.py`, `main.py`, `utils.py`); they import each other with
|
|
plain `from x import y`, so `src/` must stay on `sys.path` for anything that
|
|
imports them (see `webapp/app.py` for how the web GUI does this).
|
|
- No comments explaining *what* code does — only *why*, when it's non-obvious
|
|
(e.g. a workaround, an invariant, a subtle constraint).
|
|
- Don't add abstractions, config flags, or error handling for cases that
|
|
can't happen. Keep changes scoped to what was asked.
|
|
- Type hints are used inconsistently today (see `utils.py` vs `file_io.py`);
|
|
match the style of the file you're editing rather than mixing conventions.
|
|
|
|
## Secrets & data
|
|
|
|
- `.env` (real secrets, gitignored) vs `.env.example` (committed template) —
|
|
keep them in sync whenever a new config key is added.
|
|
- Participant CSV data lives outside the repo (`CSV_PATH`), never commit
|
|
sample data containing real names/emails.
|
|
- The web GUI can trigger real emails to real people via `run_draw()` — treat
|
|
"run draw" as a destructive/one-way action (it also overwrites this year's
|
|
CSV) and confirm with the user before wiring up anything that calls it
|
|
automatically (e.g. a cron/scheduled container).
|
|
|
|
## Deployment
|
|
|
|
- `Dockerfile` builds the web GUI service; `docker-compose.yml` wires it up
|
|
with a volume for `CSV_PATH` and an `.env` file for config. See the
|
|
README's Docker section for usage.
|