Contribute¶
These pages are for contributors who change chalkos itself. chalkos takes changes as pull requests
against main on GitHub. A change is ready when it carries
its tests, the documentation it affects, formatted code, and passing flake checks for what it
touches.
Start¶
These pages take a first change from setup to commit.
-
Development setup
The development shell, the repository layout and the commands of a development loop.
-
Common changes
Checklists for an API method, a chalkctl command, a built-in kind, a router feature and a layer.
-
Code conventions
Compatibility, layout, layers, feature toggles, refusals, comments, golden files, generated files and commit messages.
-
Testing
Unit, namespace, evaluation and end-to-end tests, and when to write which.
-
Continuous integration
Pull requests, the tiers of checks CI runs, the e2e labels, the nightly run and the binary cache.
-
Release chalkos
The release pull request, the release workflow that publishes and signs a release, its dry run and the repository's settings for the first release.
-
Dependency updates
Renovate's groups and automerge, the fixup workflow, the weekly flake update and the vendor hash.
Code¶
These pages map the code, its packages and its internals.
-
Architecture for developers
Where Nix and Go meet, how a layer splits across the code, and where to make each kind of change.
-
Packages and programs
Every Go program in
cmd/and package inpkg/, grouped by area. -
Internals
The code behind the node API, layer plugins, redaction, the sandbox, the install, staging and storage matching.
-
Nix code
How the Nix code is laid out, what a module gets, where a new helper goes and the practices the Nix code follows.
Docs¶
These pages explain how the documentation is built and written.
Plans¶
This page lists what chalkos does not do yet.
-
Roadmap and known limits
What chalkos does not do yet, and what is planned.
Where to start¶
Start with First change in 10 minutes: it takes a small change from a fresh clone to a commit. Then read Architecture for developers for where things live, and Common changes for the steps of a frequent change. The roadmap lists good first changes, what chalkos does not do yet and the known limits of what it does.
What a change needs¶
A change needs:
- Tests at the cheapest level that proves the behaviour: a Go unit test, a test in a network namespace or on a disk image file, or a Nix evaluation test. A test in a virtual machine is for what needs a booted node, and extends an existing end-to-end test where it can. Testing explains which to write and the budget the VM tests keep to.
- Documentation of what the change does for a user: the command help in
pkg/chalkctl/help.go,pkg/chalkctl/layers/*/help.go,pkg/chalklab/help.goorpkg/chalkbuild/help.go, an option's description inmodules/, a comment in a proto file belowapi/chalkos/, and the hand-written pages it affects. Writing documentation explains how. - Formatting and linting:
nix fmtformats the Nix files,gofmtthe Go code, and go vet and staticcheck lint the Go code. - The flake checks of what it touches, which Testing maps to the parts of the repository.
- The generated files its sources produce, and a commit message of the form the code conventions give.
- A pull request whose CI run passes, with the end-to-end labels the change needs, which Continuous integration lists.