Skip to content

Contribute

The work occurs in public, and these are the rules that the project holds itself to. They are short. Each one exists because it protects something: a person, a machine, or a fact.

Safety first, and in that order

  • The hardware chain is the safety boundary. Software only adds gates on top of it. LASER_ON is never a bare GPIO. The kernel laser latch is locked by default, and each close of the pulse device locks it again.
  • Never defeat a switch, in hardware or in software, not even for a test.
  • The order of work is absolute: emission and motion first, robustness and hygiene after. A change that touches emission or motion is reviewed for that before anything else.
  • A change that can put energy where it was not commanded gets a regression test with the feature or fix, not after it.
  • Position counters are not proof of physical motion. The head accelerometer is.

The safing chain itself is described in Safety.

Proof before done

A feature or fix is not complete until it is proven. The order of preference:

  1. A host test that runs in CI (Test). The null-sink controller build lets the laser-stream and armed-window harnesses run without hardware.
  2. A bench drill on the bench reference, recorded in the commit message that carries the change.
  3. Documented reasoning.

Also:

  • Add an acceptance test only for what needs the machine or an operator, and keep the coverage maps of the catalog current (Test, "Coverage currency"). A behavior change with no catalog consequence names its host test in the commit message.
  • Push a source repository before you bump its pin. Verify the pin with bitbake -c fetch (Release flow).
  • Kernel and BSP changes ride one image flash, in a batch. Validate a .ko or overlay change on the image that ships it (The bench).
  • Remove what you put on the bench, in the same session (The bench, "Bench hygiene").

Documentation

  • One home. A fact lives on this site, or it does not exist. A repository README says what the repository is, how to build and test it, and where the documentation is. Nothing else.
  • Present tense, present state. The site describes the machine and the firmware as they are. There is no history narrative and no status document: what was done, how it was proven, and what it replaced belong in the commit message that carried it, where the change and its record stay together. Open items (bugs, feature requests, enhancements) are tracked as GitHub issues once the repositories accept them; this site has no roadmap page.
  • The currency rule. A change carries a documentation commit when it adds, removes, or renames an interface, or when it corrects a measured fact. The interfaces are a sysfs attribute, an HTTP route, a settings key, and a G-code or $ setting. The lint that catches drift is on This site.
  • Cite the measurement. A measured fact says how it was obtained, and on what: unless the page says otherwise, a measurement on this site was taken on the bench reference, and it is written so a reader can tell a measurement from a specification.
  • Public hygiene. No paths from anyone's workstation. No identity of the bench machine. American English. No em dashes.
  • Simplified Technical English. All text follows ASD-STE100. That means short sentences, one instruction for each sentence, the active voice, and the imperative in procedures. It also means the approved words in their approved meanings, and consistent technical names. Warm and direct is good. A joke that shades a fact is not.

scripts/check-style.py in the documentation repository enforces the mechanical parts (This site).

Code

  • Comments and log text obey the same rules as the documentation: present tense, Simplified Technical English, no history, no workstation paths.
  • Each new file carries an SPDX-License-Identifier line under the license of its repository (Developers, "Licenses").
  • A fork of a third-party project (e.g. the grblHAL core) carries the minimum change and no rationale comments. The reasoning goes in the commit message.

Sign your work

Every commit carries a Signed-off-by line, which git commit -s adds:

Signed-off-by: Your Name <your.email@example.com>

It certifies the Developer Certificate of Origin 1.1, the same statement the Linux kernel and grblHAL use, and the full text sits in CONTRIBUTING.md in each repository. Use your real name.

Signing off is not a copyright assignment. You keep the copyright in what you write, and your contribution is accepted under the license of the repository it goes to; the project asks for no transfer of rights and has no contributor license agreement.

A patch adds no copyright line. A change to an existing file leaves its header alone, and the contribution is recorded by its sign-off and by git. If you write a whole new file, put your own name in its copyright line or leave the line out - either way it carries the SPDX-License-Identifier for that repository's license.

Where to talk

  • The community forum for questions and bench reports.
  • The issue tracker of the repository that holds the code, for defects and proposals.