# Contributing

This is one of the six sites on the [Bennett platform](https://git.thebennett.net/austin/platform):
a Spring Boot 4 / Java 25 backend serving a Vite + React SPA from a single jar. The workflow below is
the same for every app — once you know one, you know all of them.

**The one rule:** `main` is protected. You cannot push to it. Every change lands through a pull request
whose CI passed. There is no exception, including for the repo owner — the server enforces it, so a
`git push origin main` will be rejected.

---

## Prerequisites

| Tool | Version | Notes |
|---|---|---|
| JDK | 25 | `java -version` should say 25 |
| Maven | 3.9+ | or use the platform image below |
| Docker | any recent | **required to run the tests** — they use Testcontainers (a real Postgres) |
| Node | — | *not* installed by hand; the Maven build downloads a pinned Node and runs the SPA build |

You also need a **Gitea Maven token** to build, because the platform (`net.thebennett.platform:*`) is
pulled from the Gitea package registry, not Maven Central. Create a token at
`git.thebennett.net → Settings → Applications` with `read:package` scope, then export it:

```sh
export MAVEN_USER=<your-gitea-username>
export MAVEN_TOKEN=<the-token>
```

The repo ships `.gitea/ci-settings.xml`, which wires that registry up using those two variables — pass
it with `-s` and you never have to touch your global `~/.m2/settings.xml`.

---

## Build and test locally

```sh
# Full verify — compiles, builds the SPA, runs every test (needs Docker running).
mvn -B -s .gitea/ci-settings.xml verify

# Faster inner loop — skip the frontend build when you're only touching Java.
mvn -B -s .gitea/ci-settings.xml -DskipFrontend=true verify

# Run the app locally (Postgres + any OIDC/storage config supplied via env — see the app's README).
mvn -s .gitea/ci-settings.xml spring-boot:run
```

If `verify` fails with a Docker or "could not start container" error, the daemon isn't running — the
tests need it. Tests will not be skipped to work around this; a green build means the tests actually ran.

### Frontend

The SPA lives in `frontend/`. For a fast UI loop with hot reload:

```sh
cd frontend
npm install
npm run dev        # Vite dev server, proxying /api to the running backend
```

For anything that ships, let Maven build it (`mvn verify` runs `npm ci && npm run build` and folds
`dist/` into the jar) so what you test is what deploys. The frontend is **vendored per app** — there is
no shared frontend package, so a shared component you change here does not change in the other apps.

### Tests

- Name test classes `*Test` — Surefire runs those. A class named `*IT` is silently skipped.
- Integration tests use Testcontainers (`@ServiceConnection` + a real `postgres` container). No mocks
  for the database.
- Every app inherits a set of **contract tests** from `platform-starter-test` (unknown `/api` paths 404,
  health is UP, probes exist, SPA routes forward to `index.html`). You get these for free by extending
  the platform's base test — don't reimplement them.
- Protected-page paths return **302 for a browser** (`Accept: text/html`) and **401 for a fetch/XHR**
  (`Accept: */*`). If you're asserting that `/admin` "redirects to login," send the browser Accept
  header or the assertion will see a 401 and mislead you.

---

## The change workflow

```sh
git switch -c feature/short-description        # branch off main
# ... make your change, add tests ...
mvn -B -s .gitea/ci-settings.xml verify        # green locally before you push
git push -u origin feature/short-description    # push the BRANCH, never main
```

Then open a pull request against `main` (Gitea → *New Pull Request*, or `tea pr create`). CI runs on the
PR. When the check is green, merge it. On merge the image builds, publishes, and deploys automatically.

### What CI does (`.gitea/workflows/build.yml`, job `build-and-publish / build`)

Runs on every PR **and** on push to `main`:

1. **Test** — runs `mvn verify` in a sibling Maven container (Testcontainers can't run inside
   `docker build`). Tests gate both the build and the merge.
2. **Build image** — `docker build` (which also runs the SPA build); a broken Dockerfile fails here.
3. **Scan image (Trivy)** — fails on any fixable **HIGH/CRITICAL** library CVE. A new bad CVE blocks
   the merge even if your code is fine — bump the offending dependency.
4. **Push image** — **only on push to `main`** (`if: github.event_name != 'pull_request'`). PRs build
   and scan but never publish.

`main` requires the check **`build-and-publish / build (pull_request)`** to be green before merge. That
context name is what branch protection is pinned to; if you rename the workflow or job, update the
required-check setting to match or nothing will ever be mergeable.

Commits that only touch `**.md` or `renovate.json` skip the build on `main` (they can't change the
image) — but a PR that touches them still runs the PR check.

---

## Dependencies

Renovate watches this repo. Platform version bumps (`net.thebennett.platform`) are **auto-merged** once
their PR is green — that's how a security fix in the platform reaches every app without hand-editing six
`pom.xml` files. Other updates open PRs for a human to merge. Don't hand-bump the platform version to
chase a fix; cut a platform release and let Renovate carry it here.

Some toolchain upgrades are intentionally pinned back (e.g. ESLint / TS majors blocked by plugin peer
caps). If a Renovate PR is red on a peer-dependency conflict, that's why — don't force it.

---

## Deploy

Merge to `main` → CI publishes `:latest` and `:<sha>` to the Gitea registry → **Watchtower** pulls the
new `:latest` and restarts the container → **Caddy** fronts it. There is no manual deploy step and no
staging hop; the PR gate *is* the safety net, which is why the tests and scan are non-negotiable.

To force an urgent redeploy without a code change (e.g. rolling out a platform fix immediately), trigger
the workflow manually (`workflow_dispatch`) rather than pushing an empty commit.

---

## Conventions

- **Business logic lives in Java.** This is a Spring app, not a React app with a Java proxy — the server
  owns the data, the rules, and the validation. The SPA renders and calls `/api`. Prose and layout stay
  in the markup; only the parts that change without the page changing (prices, lists, links) become data.
- Keep commits scoped and their messages in the imperative ("add booking link", not "added").
- Don't commit secrets. Config comes from environment variables at deploy time (see the app's README for
  the list); there is no `.env` in the repo.
- Update the README when you change what the server owns or what env vars it needs — that's the file the
  next person reads first.