Contribution workflow¶
About this chapter Contribution workflow
In this chapter
- Contribution workflow
- Start from current main
- Build continuously
- Test narrowly, then broadly
- Code expectations
- Generated artifacts
- Documentation ownership
- Pull-request description
- Commit quality
- Reviewability
- First contribution strategy
- Security issues
- Evidence should match patch scope
- Compatibility review
- Keep compatibility changes explicit
- Before opening the PR
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¶
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.
| Area | Primary source area |
|---|---|
| CPU, memory, interrupts, SMP, processes | kernel/metal/ |
| storage, filesystem, installer | kernel/fs/ |
| graphics, input, 3D, GPU | kernel/gfx/ |
| desktop and windows | kernel/wm/ |
| networking | kernel/net/ |
| ChrisC, CLVM, JIT and toolchain | compiler/ and kernel/lang/ |
| guest applications | APPS/, GAMES/, LIB/, SYS/ |
| ChrisVM | chrisvm/ |
Preserve the boundary unless the change genuinely requires an architectural interface change.
Build continuously¶
Choose the narrowest build that exercises your change:
for kernel-only work,
for normal system integration, and
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:
After the narrow path is stable, expand to the relevant broad set:
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:
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:
- What behavior is being changed?
- Which subsystem owns that behavior?
- What invariant or interface changed?
- Which commands prove the intended result?
- 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.
Evidence should match patch scope¶
The validation record should be proportional to the changed boundary.
A documentation-only wording correction does not require pretending that the kernel was requalified on physical hardware. A storage-driver change should not stop at an unrelated compiler unit test. A format change should include compatibility or rejection evidence, not only a successful build.
The goal is not to maximize the number of commands in a pull request. It is to select tests whose oracles directly exercise the invariant, interface or failure path that changed, then add broader gates as regression confirmation.
Compatibility review¶
Before merging a change to an ABI, serialized format, syscall, object format or boot contract, explicitly answer whether existing producers and consumers remain compatible.
If compatibility changes, the pull request should identify the affected version, migration or rejection behavior and the tests that exercise old and new artifacts. Treating a compatibility change as an ordinary refactor makes future debugging substantially harder.
Keep compatibility changes explicit¶
If a patch changes an on-disk format, bytecode image, ABI, boot contract or public resource semantics, state that fact separately from the implementation summary.
Reviewers should be able to identify:
- whether old artifacts remain readable;
- whether new writers emit a new version;
- whether migration is required;
- whether unknown versions or flags fail closed;
- which regression fixtures cover compatibility.
Do not hide a compatibility change inside a broad refactor. The cost of an explicit version decision is much lower than diagnosing silent cross-revision breakage later.
Before opening the PR¶
Run:
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.