Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (90 loc) · 5.92 KB

CONTRIBUTING.md

File metadata and controls

123 lines (90 loc) · 5.92 KB
Raw

Contributing

Thanks for working on a Bespok3d plugin. Bespok3d is a printer-agnostic plugin manager for Klipper printers that runs on stock firmware, with no custom-firmware flashing. This repo publishes one or more plugins as signed .b3 packages that the desktop app installs onto a printer through the on-printer daemon. See README.md for this repo's layout, build, and release mechanics.

Before you write code

Read CLAUDE.md. It is the contract for changes here: the plugin model (a plugin declares WHAT the printer should end up with, never a script that runs on the printer), the non-negotiables (RULE ZERO: no em-dash or en-dash; every identifier carries domain meaning; nesting beyond one level is suspicious; rule of three; extend upstream additively; never commit a real secret or LAN value), and the working procedure. If you use an AI assistant (many contributors do), point it at that file; AGENTS.md sends non-Claude tools there too.

Writing a plugin of your own? The full plugin documentation lives with the build tool: Bespok3d/b3-builder/doc. It covers the anatomy of a plugin, its manifest and its .b3 package, the six kinds of plugin, signing, the release Action, channels, local testing and publishing.

Quick start: from clone to pull request

Six steps. A change is ready for review when all six are done and the gate is green.

1. Install the tools

Tool Why macOS Linux
git 2.23 or newer git switch and cloning submodules in one pass preinstalled, or brew install git sudo apt install git
Python 3.11 the printer's runtime; the gate pins it and refuses to run on another version brew install python@3.11, or brew install uv install uv (curl -LsSf https://astral.sh/uv/install.sh | sh) and the gate provisions 3.11 itself
Node 20 or newer runs the shared detectors (the em-dash guard, workflow pinning) brew install node nvm install 20; distro packages are usually older than 20
shellcheck lints this repo's shell scripts brew install shellcheck sudo apt install shellcheck
GitHub CLI (optional) opens the pull request from the terminal brew install gh see cli.github.com

You also need an SSH key on your GitHub account (ssh -T git@github.com should greet you by name) and access to the Bespok3d org: these repos are private during the beta, so ask the maintainer to add you before you clone.

The gate builds its own Python tool venv under lib_bespok3d/tooling/ the first time you run it. Nothing is installed into your system Python.

2. Clone with the submodule

lib_bespok3d carries the shared gate helpers and the workspace detectors, and nothing in this repo checks out green without it. Changes are made on dev, so clone that branch:

git clone --recurse-submodules --branch dev git@github.com:Bespok3d/networking.git
cd networking

Already cloned, or seeing lib_bespok3d/tooling/gate-lib.sh: No such file or directory? Run this once from the repo root:

git submodule sync --recursive && git submodule update --init --recursive

The sync half matters on an existing clone: it repoints the submodule at the relative URL, so the submodule is fetched over whatever protocol you cloned this repo with. Without it, a clone made over SSH still tries to fetch the submodule over HTTPS and stops at a Username for 'https://github.com': prompt.

3. Branch off dev

git switch dev && git pull
git switch -c <short-name-for-your-change>

4. Make the change

Only what your user story needs. Keep the plugin's doc/README.md and doc/CHANGELOG.md current when behavior or config changes, and add a regression test where the repo has a test layer for it. The rules the reviewer applies are in CLAUDE.md, and RULE ZERO (no em-dash, no en-dash) covers your commit message too.

5. Run the gate until it is green

bash scripts/check.sh

It runs the shared workspace detectors (the em-dash guard, workflow pinning, shellcheck) plus whatever language layer the plugin ships (ruff, mypy and pytest for a plugin that carries Python). On a failure, fix the cause. If a detector is genuinely wrong about one line, justify that one line at the smell (# gate-allow <metric>: <reason>); never mute a check to make a number go down.

6. Commit, push and open the pull request

git commit -am "<what changed and why>"
git push -u origin <your-branch>
gh pr create --base dev --fill      # or open the link that git push prints

The pull request targets dev. CI runs this same scripts/check.sh on it, so a red gate is not reviewable and blocks the release.

Release

Bump a plugin's manifest.json version. On merge, the b3-builder CI Action packs the .b3, signs it, cuts a release, and registers it in the org index. Do not hand-edit index.json, the .atom.json, index.json.sig, or anything under dist/: those are generated and signed by CI.

A version bump also changes what the desktop app bundles offline, and the app keeps a committed snapshot of that bundle. Once your manifest change is in, run npm run golden:refresh in the Bespok3d-desktop checkout and commit the refreshed snapshot with it: the app's gate stays red until someone does.

What a good change looks like

  • Scoped to a clear user story; only what the story needs.
  • Follows the rules in CLAUDE.md; passes the gate green.
  • Ships a regression test where the repo has a test layer for the behavior, in the same change.
  • Keeps the plugin's doc/README.md and doc/CHANGELOG.md current when it changes behavior or config.

Constraints

  • The maintainer owns git history and releases; submit changes as a pull request against dev.
  • Never SSH-mutate or reconfigure a live printer without explicit authorization; a serial port on a printer may be a live Klipper MCU link. Read-only diagnosis is fine.