|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thanks for working on a Bespok3d plugin. Bespok3d is a printer-agnostic plugin manager for Klipper |
| 4 | +printers that runs on stock firmware, with no custom-firmware flashing. This repo publishes one or |
| 5 | +more plugins as signed `.b3` packages that the desktop app installs onto a printer through the |
| 6 | +on-printer daemon. See [README.md](README.md) for this repo's layout, build, and release mechanics. |
| 7 | + |
| 8 | +## Before you write code |
| 9 | + |
| 10 | +Read [CLAUDE.md](CLAUDE.md). It is the contract for changes here: the plugin model (a plugin declares |
| 11 | +WHAT the printer should end up with, never a script that runs on the printer), the non-negotiables |
| 12 | +(RULE ZERO: no em-dash or en-dash; every identifier carries domain meaning; nesting beyond one level |
| 13 | +is suspicious; rule of three; extend upstream additively; never commit a real secret or LAN value), |
| 14 | +and the working procedure. If you use an AI assistant (many contributors do), point it at that file; |
| 15 | +`AGENTS.md` sends non-Claude tools there too. |
| 16 | + |
| 17 | +## Develop |
| 18 | + |
| 19 | +```sh |
| 20 | +bash scripts/check.sh |
| 21 | +``` |
| 22 | + |
| 23 | +The gate needs the `lib_bespok3d` submodule; if you cloned without it, run |
| 24 | +`git submodule update --init` first. It runs the shared workspace detectors (the em-dash guard, |
| 25 | +workflow-pinning, shellcheck) plus whatever language layer the plugin ships (ruff, mypy, and pytest |
| 26 | +for a plugin that carries Python). Run it before every push; CI runs the same gate and blocks a |
| 27 | +release on failure. |
| 28 | + |
| 29 | +## Release |
| 30 | + |
| 31 | +Bump a plugin's `manifest.json` `version`. On merge, the `b3-builder` CI Action packs the `.b3`, |
| 32 | +signs it, cuts a release, and registers it in the org index. Do not hand-edit `index.json`, the |
| 33 | +`.atom.json`, `index.json.sig`, or anything under `dist/`: those are generated and signed by CI. |
| 34 | + |
| 35 | +## What a good change looks like |
| 36 | + |
| 37 | +- Scoped to a clear user story; only what the story needs. |
| 38 | +- Follows the rules in CLAUDE.md; passes the gate green. |
| 39 | +- Ships a regression test where the repo has a test layer for the behavior, in the same change. |
| 40 | +- Keeps the plugin's `doc/README.md` and `doc/CHANGELOG.md` current when it changes behavior or config. |
| 41 | + |
| 42 | +## Constraints |
| 43 | + |
| 44 | +- The maintainer owns git history and releases; submit changes as a pull request against `dev`. |
| 45 | +- Never SSH-mutate or reconfigure a live printer without explicit authorization; a serial port on a |
| 46 | + printer may be a live Klipper MCU link. Read-only diagnosis is fine. |
0 commit comments