docs: add engineering contract, contributor toolkit and templates
Add AGENTS.md as the single engineering contract: sources of truth,
evidence and proof requirements, ownership, working modes, the reviewed
change loop, maintenance isolation, decision authority, dependency and
fork rules, the 0.0.x to 0.1.0 release progression, and branch and
publication rules.
Add .agents/ with scope, implement, verify, maintenance and release
procedures; reviewer, architecture debt scout, simplicity and refactoring
roles; skills for the compositor, Servo rendering, runtime capabilities,
appd sessions, packages and data, Linux deployment, integration
verification and documentation; and verify.py, which runs the existing
check profiles with --locked from any directory, stops on the first
failure and supports --dry-run.
check_toolkit.py validates local links and heading anchors, metadata,
catalog coverage and issue forms. A new contributor-toolkit CI job runs
both. The structure follows the Resina Design System toolkit at
1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT.
Validation, against the committed lockfiles:
- verify.py toolkit: checker passes, 28 runner/checker tests pass
- verify.py portable, demos, packages: pass
- verify.py linux, runtime, servo-embed: fail on existing defects
(clippy collapsible_if in the winit backend, three clippy lints in
weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo
revision's servo-layout); the runner reports the failing status
Add CONTRIBUTING.md, issue forms for defects and changes, maintenance
problems and decisions of direction, and a pull request template asking
for ownership, proof and the validation actually performed. README.md
links the contribution guide.
2026-10-08 23:40:08 +00:00
|
|
|
# Contributing to WEFT OS
|
|
|
|
|
|
|
|
|
|
[AGENTS.md](AGENTS.md) is the engineering contract for every contribution,
|
|
|
|
|
manual or assisted. [BLUEPRINT.md](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](.agents/README.md) provides procedures, review roles,
|
|
|
|
|
area knowledge and a verification runner. The same files work for manual
|
|
|
|
|
development and any coding assistant; its setup table covers client
|
|
|
|
|
differences.
|
|
|
|
|
|
|
|
|
|
## Describe a verifiable change
|
|
|
|
|
|
|
|
|
|
Search [existing issues](https://github.com/marcoallegretti/WEFT_OS/issues) and
|
|
|
|
|
pull requests first, then open a
|
|
|
|
|
[new issue](https://github.com/marcoallegretti/WEFT_OS/issues/new/choose):
|
|
|
|
|
|
|
|
|
|
- **Defect or change** for a concrete problem or ordinary work within accepted
|
|
|
|
|
architecture.
|
2026-10-08 23:48:37 +00:00
|
|
|
- **Maintenance** for one present ownership, boundary, enforcement or structural
|
docs: add engineering contract, contributor toolkit and templates
Add AGENTS.md as the single engineering contract: sources of truth,
evidence and proof requirements, ownership, working modes, the reviewed
change loop, maintenance isolation, decision authority, dependency and
fork rules, the 0.0.x to 0.1.0 release progression, and branch and
publication rules.
Add .agents/ with scope, implement, verify, maintenance and release
procedures; reviewer, architecture debt scout, simplicity and refactoring
roles; skills for the compositor, Servo rendering, runtime capabilities,
appd sessions, packages and data, Linux deployment, integration
verification and documentation; and verify.py, which runs the existing
check profiles with --locked from any directory, stops on the first
failure and supports --dry-run.
check_toolkit.py validates local links and heading anchors, metadata,
catalog coverage and issue forms. A new contributor-toolkit CI job runs
both. The structure follows the Resina Design System toolkit at
1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT.
Validation, against the committed lockfiles:
- verify.py toolkit: checker passes, 28 runner/checker tests pass
- verify.py portable, demos, packages: pass
- verify.py linux, runtime, servo-embed: fail on existing defects
(clippy collapsible_if in the winit backend, three clippy lints in
weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo
revision's servo-layout); the runner reports the failing status
Add CONTRIBUTING.md, issue forms for defects and changes, maintenance
problems and decisions of direction, and a pull request template asking
for ownership, proof and the validation actually performed. README.md
links the contribution guide.
2026-10-08 23:40:08 +00:00
|
|
|
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](AGENTS.md#8-maintenance)
|
|
|
|
|
separates a present problem from a cleanup preference.
|
|
|
|
|
|
|
|
|
|
## Find the owner
|
|
|
|
|
|
|
|
|
|
Each component owns specific responsibilities, listed in the blueprint's
|
|
|
|
|
[ownership table](BLUEPRINT.md#4-architecture-and-ownership). Public contracts
|
|
|
|
|
are the package manifests, the [host WIT](crates/weft-runtime/wit/weft-app.wit),
|
|
|
|
|
the [shell protocol](protocol/weft-shell-unstable-v1.xml) and the
|
|
|
|
|
[IPC types](crates/weft-ipc-types/src/lib.rs). Selected dependency APIs are
|
|
|
|
|
those in [Cargo.lock](Cargo.lock), including the Servo fork and the Stylo revision.
|
|
|
|
|
|
|
|
|
|
## Prove and implement the change
|
|
|
|
|
|
|
|
|
|
Follow the [reviewed change loop](AGENTS.md#5-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](AGENTS.md#6-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](AGENTS.md#14-branches-commits-and-publication) list what to avoid.
|
|
|
|
|
|
|
|
|
|
Install the native dependencies from [docs/building.md](docs/building.md) and
|
|
|
|
|
run the relevant [runner](.agents/README.md#verification-runner) profiles, for
|
|
|
|
|
example:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
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](.agents/commands/verify.md) 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](.github/pull_request_template.md) 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.
|