# Contributing Contributions to **Volumen** are governed by the Contributor terms below; submitting one means you accept them. ## Contributor terms 1. This project belongs to its owner alone. The owner decides what is accepted, in what form and when; the decision is final and needs no justification. 2. By submitting a contribution you assign to Petr Balvín all present and future copyright and related rights in it, worldwide, for the full term of the rights, with the right to relicense and sublicense without restriction, including under proprietary terms. 3. Where that assignment is not effective, it counts as a perpetual, irrevocable, royalty-free licence with the same scope. 4. To the fullest extent permitted by law, you waive any right of attribution and integrity in the contribution. The project names no contributors and keeps no credits list. 5. By submitting you represent that the work is yours and that you hold the rights to assign it as above. ## Development setup Requirements: Go 1.27.1 (the version the `go` directive in `go.mod` declares), [just](https://github.com/casey/just) for the recipes, Perl for the scripted recipes (`just test` and `just fmt-check` are Perl, builtins only), and gcc for the race detector, which `just race` and `just gates` run. The build itself is pure Go with `CGO_ENABLED=0`. ```sh git clone https://sourcedock.dev/petrbalvin/volumen.git cd volumen just build just test ``` `just dev` serves the content directory `./posts` and the local `config.toml` on ; the config and the state files are git-ignored. On a fresh checkout the first visit to `/admin` shows the first-run wizard; it creates the developer's account with any password the policy accepts. For a real install there is no bootstrap command: copy `config.toml.example`, start the server, complete the wizard; [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) has the full production setup. The direct dependency set is fixed: scriptorium (Markdown, mathematics and diagrams), bluemonday (sanitisation), interpres (TOML), `golang.org/x/crypto` (scrypt) and `golang.org/x/text` (NFKC). A new third-party module needs a justification that survives review. ## Workflow 1. Branch from `development`. Never commit directly to `main`, which is release-only. 2. Commit in [Conventional Commits](https://www.conventionalcommits.org/) form: `type(scope): description`, subject line only, imperative mood, lowercase after the colon, no trailing full stop. Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `revert`. 3. One logical change per commit. A refactor, a behaviour change and a formatting pass are three commits, never one. 4. Record every user-visible change in `CHANGELOG.md` under `## [development]`, using the categories `Added`, `Changed`, `Fixed`, `Removed` and `Security`. 5. Add or update tests. Coverage stays at 80 percent or more; it is a hard gate. 6. Update the documentation when the public API, the configuration or the behaviour changes: `README.md`, `docs/CONFIGURATION.md`, `docs/API.md` and `docs/ARCHITECTURE.md` are the ones that move most often. A change to the command line moves `docs/CLI.md` and `man/volumen.1` in the same commit as the flags it documents. 7. Never commit while `just gates` is red; run it locally first. 8. Open a pull request against `development`. Releases are cut by merging `development` into `main` and tagging `vX.Y.Z`. The release workflow runs the gates at the tag, builds the portable matrix and publishes the release with the notes it extracts from `CHANGELOG.md`; [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) has the detail. ## Code style `gofmt` and `go vet` run through `just fmt` and `just vet`, with zero diff and zero warnings tolerated; `just vet` is `go vet` followed by `go fix -diff`. `just gates` is the definition of done in one command, and the recipe file names what it contains. Errors are checked explicitly, wrapped as `fmt.Errorf("context: %w", err)`, and nothing panics outside `main`; diagnostics go through `log/slog`, never `fmt.Print` in library code. Names, messages and comments are in British English. The recipe file holds the commands. Tests live next to the code in `*_test.go`, use `t.TempDir()` for fixtures and `net/http/httptest` for the HTTP layer, and never start a real network server or reach the internet. Table-driven tests where the cases are enumerable; run `just race` before merging anything that shares state. Handlers live in `internal/httpapi` (public API) and `internal/admin` (admin UI), with the middleware in `internal/web`; read the security model in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) before touching auth, uploads or rendering. New source files open with the project's two-line licence header, whose SPDX identifier matches `LICENSE`. Configuration files, workflows and dotfiles do not carry it. ## AI contribution policy AI tools are welcome as productivity aids and are a normal part of modern software development. What matters is that the contribution stays understandable, reviewable and genuinely useful. - **Disclose the assistance.** If AI helped draft any part of a commit, issue, pull request or review, say so. - **Commit messages carry exactly one trailer**, on the line after the subject: ```text Assisted-by: MODEL ``` Name the model that did the work, spelled the way its maker spells it, for example `GLM 5.3`, `DeepSeek V4.1 Flash` or `Qwen 3.8 Flash`. No `Co-Authored-By`, no `Signed-off-by`, no other trailers, and no prose: the trailer is the disclosure. - **Issues and pull requests** attribute the assistance in a comment, for example `_Assisted-by: GLM 5.3_`. It does not belong in the pull request description. - **Take responsibility.** You are accountable for the accuracy, completeness and intent of everything you submit, whether or not AI produced it. - **Review before marking ready.** Read the diff carefully, run it locally, and add the tests it needs. Do not mark a pull request ready until you can defend every change in it. - **Quality over quantity.** Contributions that look like un-reviewed output, or whose author cannot engage substantively during review, may be closed. - **Preferred models.** Prefer open-weight models with transparent training data and minimal output filtering. AI assists. It does not replace judgement. ## Continuous integration Workflows live in `.gitea/workflows/` and run on the project's own runners: | Workflow | Trigger | What it does | |---|---|---| | Test | push or pull request to `development` | build, format check, vet, modernisation, the test suite with the coverage floor | | Race | dispatched by hand | the suite under the race detector, as a second opinion after the local gate | | Release | a `v*` tag | the same gates as Test, then the matrix build, the proven version and the release itself; the race detector runs locally in `just gates` before the tag is cut | The local equivalent is `just gates`, which is the same set plus the race detector. ## Reporting bugs Open an issue at `https://sourcedock.dev/petrbalvin/volumen/issues` with the version (`volumen version`), the operating system and architecture, the exact command, the full output, and the expected against the actual behaviour. **Security issues do not go in the issue tracker.** Report them as [SECURITY.md](SECURITY.md) describes.