# 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. That address is also the Go module path in `go.mod`, so
moving the canonical host rewrites every import in the tree; such a move has to
land before the first release tag, never after one.

## 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. Pick the form that matches what closes
   the issue (a bug, an enhancement, debt, a design question, or docs) and
   answer its fields; the tracker refuses a blank issue. Write it for someone
   who has never opened this repository: a title that reads on its own, the
   console's own terms explained once where they first appear, and no
   internal shorthand (milestone codes, decision numbers, change names as
   explanations, dates as narrative) and no deployment's counts or names.
   Questions go to the forum, not the tracker.
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 and the CLA

member-console is dual-licensed: `AGPL-3.0-only` for everyone, plus commercial
licenses that fund development (see [COMMERCIAL.md](COMMERCIAL.md)). Keeping
that possible requires a Contributor License Agreement from every contributor
before their work can be merged.

The CLA leaves the copyright in your contribution with you while granting
Christian Galo the right to license it under the AGPLv3 **and** under separate
commercial terms. That grant is what lets the project offer a commercial option
while staying open source by default. A Developer Certificate of Origin would
not do the same job: it attests provenance and grants no relicensing right.

The agreement is [CLA.md](CLA.md). To sign it, add one line to
[CLA-SIGNATORIES.md](CLA-SIGNATORIES.md) in a pull request from your own
account: full legal name, email, date, and the CLA version. That commit is your
signature, and it can travel in the same pull request as your first change.
Nothing is merged from an unsigned contributor.