cgalo5758
cbd08b45aa
Rewrite the README around purpose, architecture, quickstart, and status. Add contributing/security policies plus a docs index with audience front matter across existing docs.
89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
# 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).
|