Development workflow

Branches

Active development happens on main. Maintenance happens on long-lived release/<major.minor> branches (e.g. release/1.6, release/2.0). Most PRs target main; backports are explicitly requested with the cherry-pick workflow used by maintainers.

Daily loop

# 1. Pull latest
git fetch origin && git rebase origin/main

# 2. Build only what you touched
go build ./core/snapshots/...

# 3. Run tests
make test                 # unit tests, no root needed
sudo make root-test       # tests that need root (mount, cgroup, ...)
make integration          # full end-to-end against a running daemon

# 4. Lint and format
make check                # golangci-lint
make proto-fmt            # if you touched .proto

# 5. Regenerate code if needed
make protos               # only when proto files change
make vendor               # only when go.mod changes

# 6. Push and open a PR
git push origin <branch>

make ci chains lint, build, proto checks, and coverage in the same order GitHub Actions runs them.

Editing protobuf

Run make protos from the repo root and make sure your working directory is under $GOPATH — protoc's import resolution depends on it (see CONTRIBUTING.md).

Generated outputs:

• api/services/<svc>/v1/*.pb.go (gRPC types and marshallers)
• api/services/<svc>/v1/*_grpc.pb.go (gRPC server/client)
• api/services/ttrpc/.../*_ttrpc.pb.go (ttrpc shim API)
• api/runtime/task/v3/* (shim API)

api/next.txtpb is a buf descriptor of the API surface; it's regenerated by make protos and committed.

Editing built-in plugins

Built-ins live under plugins/ (and a few in core/runtime/v2). To add a new built-in:

1. Implement the plugin's init() that calls registry.Register(&plugin.Registration{...}).
2. Add a blank import to cmd/containerd/builtins/builtins.go (or one of its _<os>.go siblings if your plugin is platform-specific).
3. Add the plugin's expected config struct to Config (or implement plugin.ConfigType in your registration), so containerd config dump reflects it.
4. Document the plugin under docs/PLUGINS.md and configuration under docs/man/containerd-config.toml.5.md.

Pull request expectations

• Each commit must have a Signed-off-by: trailer (git commit -s).
• Squash any "fixup" commits before pushing for review.
• Link the issue in the PR description; mention any deprecation introduced.
• Keep proto changes in their own commit so the make check-protos failure mode is easy to diagnose.

Releases

releases/ contains per-version notes. The release workflow is automated via .github/workflows/release.yml and release-cut.yml (under the release/ subdirectory). Tagging is done manually by maintainers; the workflow builds, signs, and publishes the binaries.