Skip to content

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.

    Read

  • Common changes


    Checklists for an API method, a chalkctl command, a built-in kind, a router feature and a layer.

    Read

  • Code conventions


    Compatibility, layout, layers, feature toggles, refusals, comments, golden files, generated files and commit messages.

    Read

  • Testing


    Unit, namespace, evaluation and end-to-end tests, and when to write which.

    Read

  • Continuous integration


    Pull requests, the tiers of checks CI runs, the e2e labels, the nightly run and the binary cache.

    Read

  • 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.

    Read

  • Dependency updates


    Renovate's groups and automerge, the fixup workflow, the weekly flake update and the vendor hash.

    Read

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.

    Read

  • Packages and programs


    Every Go program in cmd/ and package in pkg/, grouped by area.

    Read

  • Internals


    The code behind the node API, layer plugins, redaction, the sandbox, the install, staging and storage matching.

    Read

  • 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.

    Read

Docs

These pages explain how the documentation is built and written.

  • Writing documentation


    How to write, build, check and preview the documentation.

    Read

  • Docs style guide


    The rules every documentation page follows.

    Read

  • Talks and slides


    The slide decks of talks on chalkos, which the site serves, and how to add one.

    Read

Plans

This page lists what chalkos does not do yet.

  • Roadmap and known limits


    What chalkos does not do yet, and what is planned.

    Read

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.go or pkg/chalkbuild/help.go, an option's description in modules/, a comment in a proto file below api/chalkos/, and the hand-written pages it affects. Writing documentation explains how.
  • Formatting and linting: nix fmt formats the Nix files, gofmt the 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.