BoilerWorks

boilerworks / docs / contributing.md

Source Rendered

Blame History Raw 55 lines

1	`# Contributing`
2
3	`## Ways to contribute`
4
5	`- Add a template — build a new stack using the [boilerworks conventions](https://github.com/ConflictHQ/boilerworks/blob/main/primers/PROCESS.md) and open a PR to add it to the catalogue`
6	`- Improve docs — fix errors, improve clarity, add examples`
7	`- Report bugs — open an issue with steps to reproduce`
8	`- Request a template — open an issue describing the stack`
9
10	`## Template conventions`
11
12	`All templates must:`
13
14	- Boot with `docker compose up -d` from scratch (no local installs required)
15	`- Use standard ports (app: 3000/8000, postgres: 5432, redis: 6379)`
16	- Use `boilerworks` as the placeholder name throughout (the renderer replaces it)
17	`- Include: Items, Categories, FormDefinitions, FormSubmissions, WorkflowDefinitions (Full only)`
18	- Have health check at `/up` or `/health/`
19	- Include a `CLAUDE.md` pointing to `bootstrap.md`
20	- Pass `make test` and `make lint`
21
22	`## CLI development`
23
24	```bash
25	`git clone https://github.com/ConflictHQ/boilerworks.git`
26	`cd boilerworks`
27	`uv sync`
28	`uv run boilerworks --help`
29
30	`make lint # ruff check + format --check`
31	`make test # pytest with coverage`
32	`make format # ruff fix + format`
33	```
34
35	`Coverage must stay at ≥ 80%.`
36
37	`## Adding a template to the catalogue`
38
39	1. Build and test the template repo (must live at `ConflictHQ/boilerworks-{name}`)
40	2. Edit `data/templates.yaml` — add an entry with `name`, `repo`, `size`, `language`, `status`, `description`, `topologies`
41	3. Run `make test` — `test_registry.py` will catch count or schema mismatches
42	`4. Open a PR`
43
44	`## Code standards`
45
46	`- Python 3.12+, fully typed`
47	- Line length: 120 (ruff config in `pyproject.toml`)
48	- `ruff check . && ruff format .` before every commit
49	`- No TODOs, no stubs`
50	`- No co-authorship messages in commits`
51
52	`## Issues and PRs`
53
54	`[github.com/ConflictHQ/boilerworks/issues](https://github.com/ConflictHQ/boilerworks/issues)`
55

BoilerWorks

Keyboard Shortcuts