195 lines
7.1 KiB
Markdown
195 lines
7.1 KiB
Markdown
# Contributing to restic-manager
|
||
|
||
Thanks for your interest in restic-manager. This document covers how
|
||
to set up a development environment, the conventions the project
|
||
follows, and how to contribute through issues as well as patches that
|
||
make it from your machine into `main`.
|
||
|
||
## Project status and scope
|
||
|
||
restic-manager is in pre-1.0. Core functionality (Phases 0–4) is
|
||
landed; OSS-readiness polish is in progress. The top of
|
||
[`tasks.md`](./tasks.md) tracks what's next; [`spec.md`](./spec.md)
|
||
is the canonical design doc and the source of truth for any
|
||
"why is it built this way" question.
|
||
|
||
The project is **single-maintainer, hobbyist-scale, and licensed
|
||
under [PolyForm Noncommercial 1.0.0](./LICENSE)**. That has two
|
||
practical implications:
|
||
|
||
1. Big PRs without prior discussion may be declined for fit
|
||
reasons even when they're correct — opening an issue first lets
|
||
us check alignment cheaply.
|
||
2. Commercial use is not permitted by the license. Bug reports and
|
||
patches from operators of personal/community deployments are
|
||
very welcome.
|
||
|
||
## Getting started
|
||
|
||
### Prerequisites
|
||
|
||
- Go 1.25 or newer (`go.mod` is the source of truth)
|
||
- `make`
|
||
- For the front-end CSS bundle: nothing extra — `make build`
|
||
downloads a pinned `tailwindcss` standalone binary into `bin/`.
|
||
- For the docs site: nothing extra — `make docs` does the same trick
|
||
with `mdbook`.
|
||
- For end-to-end tests: Docker + Docker Compose, plus `npx` for
|
||
Playwright.
|
||
|
||
### One-time setup
|
||
|
||
```sh
|
||
git clone https://gitea.dcglab.co.uk/steve/restic-manager.git
|
||
cd restic-manager
|
||
make build # compiles bin/restic-manager-{server,agent}
|
||
make test # full unit + integration test sweep
|
||
make lint # gofumpt + goimports + golangci-lint
|
||
```
|
||
|
||
### Running locally
|
||
|
||
For most development, the [smoke environment](./docs/e2e-smoke.md)
|
||
is the path of least resistance:
|
||
|
||
```sh
|
||
make smoke-restart # rebuilds, launches as a systemd --user unit
|
||
make smoke-logs # tail of the server log
|
||
```
|
||
|
||
Then point a browser at `http://127.0.0.1:8080`. The first run
|
||
prints a one-time bootstrap token to the log; use it to create the
|
||
admin user.
|
||
|
||
## Code conventions
|
||
|
||
### Style
|
||
|
||
- `gofumpt` for formatting; `goimports` for import grouping.
|
||
Both run via the pre-commit hook in this repo.
|
||
- `golangci-lint` with `.golangci.yml` defaults; CI rejects on lint
|
||
errors.
|
||
- UK English in identifiers, comments, log messages, and UI strings
|
||
(the misspell linter is configured for the UK locale — see
|
||
P3-X5 for the original sweep).
|
||
- Comments explain **why**, not what; avoid restating the code.
|
||
A surprising invariant or an external constraint is worth
|
||
writing down. "Adds 1 to x" is not.
|
||
- `slog` for structured logs. Never log secrets — and especially
|
||
never the merged-creds rest-server URL (see [`CLAUDE.md`](./CLAUDE.md)).
|
||
|
||
### File and package layout
|
||
|
||
- `cmd/server` and `cmd/agent` are the two binary entry points.
|
||
- `internal/` holds everything that's not part of the public Go
|
||
API (which is none of it — restic-manager isn't a library).
|
||
- Per-feature packages live under `internal/server/...` for the
|
||
control plane and `internal/agent/...` for the agent.
|
||
- `web/templates/` are HTML templates rendered with the standard
|
||
library; embedded via `web.FS`.
|
||
|
||
### Tests
|
||
|
||
- Unit tests live alongside the code as `*_test.go`. Use the
|
||
in-process sqlite store (`store.Open(":memory:")`) when you need
|
||
state — there is no test mock layer to maintain.
|
||
- HTTP handlers test through `httptest.NewServer` against the real
|
||
router; see `internal/server/http/auth_test.go` for the canonical
|
||
fixture pattern.
|
||
- End-to-end tests live in `e2e/` and run against a Docker Compose
|
||
stack. See [`docs/e2e.md`](./docs/e2e.md).
|
||
|
||
### Database migrations
|
||
|
||
- Migrations are hand-rolled SQL in `internal/store/migrations/`
|
||
and embedded via `embed.FS`.
|
||
- Prefer column-level `ALTER TABLE` over rebuilds — see
|
||
[`CLAUDE.md`](./CLAUDE.md) "Migrations" section for the FK-cascade
|
||
trap that bit migration 0007's first draft.
|
||
|
||
## Workflow
|
||
|
||
### Opening an issue
|
||
|
||
Issues are contributions too. Use them to report a bug, suggest a
|
||
feature, improve the documentation, or start a design discussion even
|
||
if you do not plan to submit a patch.
|
||
|
||
Before opening one, search the existing issues and check `tasks.md` to
|
||
see whether the topic is already tracked. Then choose the closest issue
|
||
template:
|
||
|
||
- [Bug report](./.gitea/issue_template/bug_report.md) for behaviour that
|
||
does not match the documentation or expected operation.
|
||
- [Feature request](./.gitea/issue_template/feature_request.md) for a new
|
||
capability or a change to existing behaviour.
|
||
|
||
Give the issue a specific title, keep it to one problem or proposal,
|
||
and complete the relevant template fields. If no template is an exact
|
||
fit, open a regular issue and explain the context, desired outcome, and
|
||
any alternatives you have considered. Maintainers may ask follow-up
|
||
questions or close requests that duplicate existing work or fall
|
||
outside the project's scope.
|
||
|
||
Security-sensitive reports are the exception: follow the
|
||
[SECURITY.md](./SECURITY.md) disclosure process and do not open a public
|
||
issue.
|
||
|
||
### Before opening a PR
|
||
|
||
1. **Open an issue first** for non-trivial changes. The design is
|
||
still moving; an issue lets us agree on direction cheaply.
|
||
2. Run `make lint test` locally — both must pass.
|
||
3. Match existing code style (see above).
|
||
4. Keep commits focused: one logical change per commit. Imperative
|
||
subject lines, body explaining why if it isn't obvious.
|
||
5. Don't add `Co-Authored-By` trailers — repo policy. If you used
|
||
AI assistance in writing the patch, that's fine; we just don't
|
||
pollute every commit message with attribution boilerplate.
|
||
|
||
### Pull requests
|
||
|
||
PRs target `main`. CI runs lint + tests on Linux amd64/arm64 and
|
||
Windows amd64; all three must be green to merge. Squash-merge is
|
||
the default; the PR title becomes the merge-commit subject, so
|
||
keep it short and informative.
|
||
|
||
The PR template asks for:
|
||
|
||
- A short description of what changed and why.
|
||
- A test plan (commands run, scenarios verified).
|
||
- Anything reviewers need to know to assess the change (related
|
||
issue, follow-up work, deferred concerns).
|
||
|
||
### Reporting bugs
|
||
|
||
Use the bug report issue template and include:
|
||
|
||
- restic-manager version (`server --version`) and agent version.
|
||
- restic version on the affected host.
|
||
- Steps to reproduce.
|
||
- Server and agent logs (sanitise any tokens before pasting).
|
||
|
||
For security-sensitive bugs, use the private disclosure process noted
|
||
above.
|
||
|
||
### Suggesting features
|
||
|
||
Use the feature request issue template and describe the use case (not
|
||
just the proposed solution). The roadmap in `tasks.md` shows where the
|
||
project is heading; if the suggestion fits a future phase we'll wire it
|
||
in there. If it falls outside the project's scope (multi-tenancy, SaaS,
|
||
non-restic backends — see `spec.md` §2 non-goals) we'll say so early to
|
||
save your time.
|
||
|
||
## Code of conduct
|
||
|
||
Project participation is governed by [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
|
||
The short version: be civil; assume good faith; harassment is not
|
||
tolerated.
|
||
|
||
## License
|
||
|
||
By contributing you agree that your contributions are licensed
|
||
under the [PolyForm Noncommercial 1.0.0](./LICENSE) license.
|