Contribution workflow¶

A ChrisOS contribution should be reviewable as a small engineering claim: a defined problem, a bounded code change, evidence appropriate to that claim, and documentation updated at the correct ownership layer.

Start from current main¶

git checkout main
git pull --ff-only
git checkout -b <topic-branch>

Use one topic branch for one coherent change. Avoid combining generated artifacts, unrelated cleanup, formatting rewrites and architectural changes in the same pull request.

Before editing, identify the subsystem that owns the behavior.

Preserve the boundary unless the change genuinely requires an architectural interface change.

Build continuously¶

Choose the narrowest build that exercises your change:

make kernel

for kernel-only work,

make

for normal system integration, and

make chrisvm
make chrisvm-test

for ChrisVM-focused work.

A focused build/test loop provides faster and more interpretable feedback than repeatedly invoking every gate.

Test narrowly, then broadly¶

Examples:

make host-cfs-test
make host-kcc-test
make test-qemu-gpu
make test-qemu-xhci
make chrisvm-test

After the narrow path is stable, expand to the relevant broad set:

make host-gates
make qemu-gates

If a relevant test cannot be run, state that in the pull request rather than silently implying coverage.

Code expectations¶

Contributions should preserve the constraints of systems code:

• kernel code must remain freestanding where the current subsystem is freestanding;
• do not introduce host-libc assumptions into privileged guest code;
• preserve explicit ownership and resource lifetime;
• preserve lock ordering and synchronization invariants;
• keep device/backend details behind existing abstractions where practical;
• treat ABI, file-format and wire-format changes as compatibility changes;
• prefer a targeted test over an unsupported capability statement;
• do not disable warnings-as-errors globally to hide a local problem.

A patch that makes one configuration work by violating an abstraction often creates a more expensive defect elsewhere.

Generated artifacts¶

Do not commit build/, ISO files, disk images, object files, transient logs or other generated test output.

Before opening the pull request:

git status
git diff --stat
git diff

Check that the patch contains only intended source and documentation changes.

Documentation ownership¶

The ChrisOS source repository intentionally keeps only operational documentation that must follow exact source-tree commands. Architecture, subsystem behavior, specifications, implementation status, research material and educational chapters belong in chrisos_site.

Update the source repository when the change alters:

• setup commands;
• build/run commands;
• test target names;
• contribution mechanics.

Update chrisos_site when the change alters:

• architecture;
• subsystem behavior;
• interfaces or formats;
• validation interpretation;
• capability status;
• roadmap or research context.

A change can require both.

Pull-request description¶

A useful pull request should state:

Problem:
Scope:
Architectural boundary:
Implementation:
Compatibility / ABI / format impact:
Tests run:
Results:
Not tested:
Documentation changed:

For a bug fix, include the observable failure and, when possible, a regression test.

For a new capability, avoid presenting code presence as proof of completion. Tie the claim to the evidence that was actually executed.

Commit quality¶

Keep commits understandable and scoped. The exact commit style can evolve, but the history should allow a reviewer to understand why a change happened and which behavior it modifies.

Avoid commits that mix:

• automatic formatting of unrelated files;
• generated binary artifacts;
• code movement with behavior changes when separation is practical;
• documentation generated by the build with hand-authored source.

Reviewability¶

A reviewer should be able to answer five questions without reconstructing the entire project:

1. What behavior is being changed?
2. Which subsystem owns that behavior?
3. What invariant or interface changed?
4. Which commands prove the intended result?
5. What relevant environment was not tested?

If those answers are unclear, the patch is too broad or the pull-request record is incomplete.

First contribution strategy¶

A first contribution should usually target a bounded defect, test, documentation mismatch or isolated subsystem improvement rather than a cross-cutting redesign.

A good first patch often has one of these shapes:

• add a regression test for a reproducible bug;
• fix a deterministic host-test failure;
• improve an error path with a focused gate;
• correct an operational command that no longer matches the source tree;
• improve a subsystem without changing public formats;
• reconcile canonical documentation with verified implementation behavior.

The goal is not to avoid difficult work; it is to establish a reviewable feedback loop before changing several architectural layers at once.

Security issues¶

Follow the repository security policy for vulnerabilities or reports that should not be disclosed through a normal public pull request. Do not publish sensitive exploit details merely to satisfy the ordinary contribution workflow.

Before opening the PR¶

Run:

git status
./scripts/check-dev-env.sh
make <narrow-target>
make <relevant-test>

Then run the broadest practical gate for the affected area. Record exact results and skips.

Contribution quality in ChrisOS is defined less by patch size than by traceability: the source change, evidence and documentation should tell one consistent story.