WEFT_OS/CONTRIBUTING.md
Marco Allegretti 722cd7479e
docs: stop runner toolchain installs and widen maintenance form
The verification runner inherited rustup's default of installing a
missing pinned toolchain or component on demand, contradicting its
documented guarantee. Run every profile with RUSTUP_AUTO_INSTALL=0 so a
missing toolchain fails the check, and document how to install it.

The maintenance form and CONTRIBUTING described only duplication and
fallback problems, while the architecture debt scout also reports
ownership, untrusted-authority and unenforced-grant problems through that
form. Widen both descriptions to match. Correct the README CI trigger to
pushes to main and pull requests.

This branch builds on docs/add-stability-blueprint, which adds the
BLUEPRINT.md the contract and toolkit checks link to; merge that first.

Validation, against the committed lockfiles:
- verify.py toolkit: checker passes, 28 tests pass
- verify.py portable packages: pass
2026-10-09 08:34:48 +00:00

3.5 KiB

Contributing to WEFT OS

AGENTS.md is the engineering contract for every contribution. BLUEPRINT.md describes the accepted product direction toward 0.1.0. This guide points to the workflow; the contract defines the requirements.

The contributor toolkit provides procedures, review roles, area knowledge and a verification runner.

Describe a verifiable change

Search existing issues and pull requests first, then open a new issue:

  • Defect or change for a concrete problem or ordinary work within accepted architecture.
  • Maintenance for one present ownership, boundary, enforcement or structural problem outside active development.
  • Decision for a material change of product direction, public compatibility, trust boundaries, support scope or data policy. Opening it does not approve the change.

Each form asks for observed and expected behavior, evidence, the owning component, present impact, an acceptance criterion and the proof that would show the change works. The maintenance threshold separates a present problem from a cleanup preference.

Find the owner

Each component owns specific responsibilities, listed in the blueprint's ownership table. Public contracts are the package manifests, the host WIT, the shell protocol and the IPC types. Selected dependency APIs are those in Cargo.lock, including the Servo fork and the Stylo revision.

Prove and implement the change

Follow the reviewed change loop: confirm scope, name the proof, implement, validate, review the actual diff, correct and commit atomically. Reproduce a defect before fixing it. Compilation, mocks and capability declarations do not prove rendering, native input, isolation or persistence; see proof before implementation.

Branch from the current main with a descriptive name such as fix/authorize-session-messages or refactor/share-servo-frame-loop; the branch rules list what to avoid.

Install the native dependencies from docs/building.md and run the relevant runner profiles, for example:

python .agents/scripts/verify.py portable linux
python .agents/scripts/verify.py servo-embed
pip install -r .agents/scripts/requirements.txt
python .agents/scripts/verify.py toolkit

verify maps each kind of change to its profiles and to the evidence the runner cannot provide, such as a running compositor, real pixels, actual components or a booted image. Report checks that could not run and why.

Submit a pull request

The pull request template asks for the problem and scope, what changed, ownership, what proves it, the validation actually performed, manual verification and material limitations. Write for a maintainer who has no access to your working notes: no attribution, generated-by or co-author trailers, prompts or process narration.

Contribution work is reviewed from its actual diff, preferably by someone who did not write it. Maintainers decide merges and release promotion; a green CI run or a review does not merge or release anything by itself.