# Contributing to member-console

Thanks for your interest in improving the member console. This project is
developed by and for the [Wiki Cafe MSC](https://git.coopcloud.tech/wiki-cafe)
multi-stakeholder co-operative, and contributions from the wider community are
welcome.

The canonical repository lives on Gitea at
**git.coopcloud.tech/wiki-cafe/member-console**. Issues, discussion, and pull
requests happen there.

## Getting set up

Follow the [Quickstart in the README](README.md#quickstart-local-development) to
bring up the test stack and run the console from source. The full stack contract
(ports, secrets, teardown, running multiple worktrees at once) is documented in
[`test/AGENTS.md`](test/AGENTS.md).

## Building and testing

Compile the binary to `./member-console`:

```bash
make build
```

Run the unit tests — database- and Stripe-backed tests self-skip without a
database:

```bash
go test ./...
```

For the full suite, point `TEST_DATABASE_URL` at a migrated Postgres (the test
stack works). [docs/testing.md](docs/testing.md) covers what each kind of test
exercises and how to run them. After a schema change, regenerate the sqlc query
code with `make sqlc-generate` (see
[docs/database-management.md](docs/database-management.md)).

## How changes are made

1. **Open an issue first** for anything non-trivial, so the approach can be
   discussed before code is written.
2. **Substantial or behavioral changes go through [OpenSpec](https://openspec.dev).**
   Proposals live under [`openspec/`](openspec/) and move through
   `proposal → specs → design → tasks` before implementation, then are archived
   once shipped. Docs-only and small mechanical fixes don't need a proposal.
3. **Branch, implement, and open a pull request** against `main`. Keep each PR
   focused on one change.

## Conventions

These are enforced by review and, where possible, by tooling. Please run the
checks below before opening a PR.

- **Strict CSP.** The app runs under `script-src 'self'` / `style-src 'self'`
  with no `unsafe-inline`. Never add inline `<script>` blocks or `style=`
  attributes — put JavaScript and CSS in `internal/embeds/static/` and reference
  it via `<script defer src>` / `<link>`.
- **Template rendering** must go through `h.Templates.Render()`. Handlers must
  not write to the `http.ResponseWriter` directly or call `.ExecuteTemplate(w, …)`.
  `make lint-templates` enforces this.
- **Every routed URL needs a handler, and every operator mutation route needs a
  walkthrough claim.** `go run . lint` checks both (`dead-route` and
  `walkthrough-coverage`).
- **Database.** Schemas are owned per module under `internal/<module>/`. Write
  migrations (goose) and queries, then regenerate with `make sqlc-generate`.
  See [docs/database-management.md](docs/database-management.md).
- **Match the surrounding code** — naming, structure, comment density, and idiom.

## Before you push

```bash
go test ./...          # unit tests (DB/Stripe tests self-skip without a database)
make lint-templates    # template-safety guard
go run . lint          # dead-route + walkthrough-coverage guard
gofmt -l .             # formatting (only your own changes need to be clean)
```

## Commit messages

Write clear, imperative-mood subject lines that describe the change ("Add
operator plan-topology view", not "changes"). Keep the body focused on *why*.

## License

By contributing, you agree that your contributions are licensed under the
project's [AGPL-3.0 license](LICENSE).