Skip to content

Commit 241d8d4

Browse files
committed
Add community health files for public contributors
SECURITY.md routes vulnerability reports to private GitHub advisories; the issue and pull-request templates prompt for a user story, reproduction steps, and the gate-green plus no-secrets checklist every change needs. Repos that lacked a CONTRIBUTING.md now carry one that points at the repo's own rules and gate.
1 parent 929b480 commit 241d8d4

5 files changed

Lines changed: 140 additions & 0 deletions

File tree

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: Bug report
3+
about: Something does not work the way it should
4+
title: ""
5+
labels: bug
6+
---
7+
8+
**What happened**
9+
A clear description of the bug.
10+
11+
**What you expected**
12+
What you thought would happen instead.
13+
14+
**Steps to reproduce**
15+
1.
16+
2.
17+
3.
18+
19+
**Environment**
20+
- Printer model and firmware version:
21+
- Bespok3d app version:
22+
- Plugin and version (if the bug is in a plugin):
23+
- Your computer's OS (for a desktop-app bug):
24+
25+
**Logs or screenshots**
26+
Anything that helps us see the failure. Please redact tokens, keys, and real network addresses.
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
name: Feature request
3+
about: Suggest a capability or an improvement
4+
title: ""
5+
labels: enhancement
6+
---
7+
8+
**The problem**
9+
What are you trying to do that is hard or impossible today?
10+
11+
**The idea**
12+
What would you like Bespok3d to do?
13+
14+
**Who it helps**
15+
As a [role], I want [capability] so that [value].
16+
17+
**Alternatives**
18+
Anything you have already tried or considered.

.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## What this changes
2+
3+
Briefly: what does this PR do, and why?
4+
5+
## User story
6+
7+
As a [role], I want [capability] so that [value].
8+
9+
## Checklist
10+
11+
- [ ] Scoped to the story above; no unrelated changes.
12+
- [ ] The repo gate passes green locally (see CONTRIBUTING.md for the command).
13+
- [ ] Ships a regression test that fails on the old behavior and passes on the fix.
14+
- [ ] No em-dash or en-dash anywhere (RULE ZERO); the gate enforces it.
15+
- [ ] Docs updated if this changes behavior, a boundary, or configuration.
16+
- [ ] No real secret, token, key, or LAN address in the diff.
17+
18+
## Notes for the reviewer
19+
20+
Anything that helps the review: a tricky decision, a follow-up you are deferring, an open question.

CONTRIBUTING.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
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.

SECURITY.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Security Policy
2+
3+
Bespok3d installs signed packages onto a networked 3D printer and runs an on-printer daemon that
4+
handles authentication and fleet access, so we take security reports seriously.
5+
6+
## Reporting a vulnerability
7+
8+
Please report security issues privately, not in a public issue or pull request.
9+
10+
Use GitHub's private vulnerability reporting: open this repository's **Security** tab and choose
11+
**Report a vulnerability**. That opens a private advisory only the maintainers can see.
12+
13+
Tell us what you found, how to reproduce it, and what an attacker could do with it. We will
14+
acknowledge your report as quickly as we can and keep you posted while we work on a fix.
15+
16+
## What matters most
17+
18+
Bespok3d runs on stock printer firmware and never flashes custom firmware. The reports we care about
19+
most are:
20+
21+
- a plugin package that can run unintended code on the printer,
22+
- a way to install or activate a package without a valid signature,
23+
- a way to bypass the daemon's authentication or reach a printer that is not yours,
24+
- a way to leave a printer unusable from a remote request.
25+
26+
## Please do not
27+
28+
- open a public issue for a security bug,
29+
- test against a printer or daemon you do not own,
30+
- run denial-of-service or destructive tests against shared infrastructure.

0 commit comments

Comments
 (0)