From 4e8b8429f58a640e6f8875fb5f42e92fc58134f8 Mon Sep 17 00:00:00 2001 From: Chris Henzie Date: Thu, 20 Aug 2026 16:39:50 -0700 Subject: [PATCH 1/2] Document contributor workflows make test can succeed while skipping tests that require root. Explain how to enable those tests and where to find CRI test prerequisites. Add pull request expectations for documentation, testing, and CI follow-up. Assisted-by: Claude Code Signed-off-by: Chris Henzie --- BUILDING.md | 5 +++++ CONTRIBUTING.md | 15 +++++++++++++++ docs/cri/testing.md | 1 + 3 files changed, 21 insertions(+) diff --git a/BUILDING.md b/BUILDING.md index b1e9673059..ae36969890 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -261,6 +261,11 @@ During the automated CI the unit tests and integration tests are run as part of - `make integration`: run all tests, including integration tests and those which require `root`. `TESTFLAGS_PARALLEL` can be used to control parallelism. For example, `TESTFLAGS_PARALLEL=1 make integration` will lead a non-parallel execution. The default value of `TESTFLAGS_PARALLEL` is **8**. - `make cri-integration`: [CRI Integration Tests](https://github.com/containerd/containerd/blob/main/docs/cri/testing.md#cri-integration-test) run cri integration tests +A test that needs `root` calls `testutil.RequiresRoot`, which skips it unless +`-test.root` is passed. `make test` skips those tests and still succeeds, so check +whether the tests covering your change are among them. `make root-test` selects +the packages that call the helper and runs them with `-test.root`. + To execute a specific test or set of tests you can use the `go test` capabilities without using the `Makefile` targets. The following examples show how to specify a test name and also how to use the flag directly against `go test` to run root-requiring tests. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24be9746c2..9383487e5f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,21 @@ $ script/setup/install-dev-tools $ make install-deps ``` +## Pull request expectations + +- Before starting work on an issue, check whether an open pull request already + addresses it: look at the issue's linked pull requests and search open pull + requests for the issue number. +- Document features and enhancements, both at the code level and in the + user-facing docs under `docs/`. +- Test at the levels that fit the change: unit, integration, or end-to-end. + For failure injection in integration tests, use the failpoint pattern + (`internal/failpoint`, `integration/failpoint`). +- Run `make check` and the tests that cover your change locally before opening + or updating a pull request. +- Monitor your pull request's CI runs and make sure your changes are not + responsible for failures. + ## Automated and AI-generated contributions Pull requests must be opened by a human. Any use of automation to create diff --git a/docs/cri/testing.md b/docs/cri/testing.md index 27742da0ac..f9bb444317 100644 --- a/docs/cri/testing.md +++ b/docs/cri/testing.md @@ -8,6 +8,7 @@ Before sending pull requests you should at least make sure your changes have pas Follow the [building](../../BUILDING.md) instructions. ## CRI Integration Test +The tests need the host dependencies installed by `make install-deps` (see [CONTRIBUTING.md](../../CONTRIBUTING.md#setting-up-your-local-environment)). * Run all CRI integration tests: ```bash make cri-integration From 4659359aae0f5bdf711f230da1e09cb9b916d0eb Mon Sep 17 00:00:00 2001 From: Chris Henzie Date: Fri, 21 Aug 2026 13:01:16 -0700 Subject: [PATCH 2/2] Add AGENTS.md guidance for AI coding agents Give coding agents an entry point to the contribution, build, and subsystem documentation. Require security findings to meet the documented scope and evidence requirements before calling them vulnerabilities. Link CLAUDE.md to AGENTS.md so both filenames provide the same guidance. Assisted-by: Claude Code Signed-off-by: Chris Henzie --- AGENTS.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 53 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..46ebdcd4fa --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,52 @@ +# AGENTS.md + +## Preparing changes + +Before contributing, read [CONTRIBUTING.md](CONTRIBUTING.md) and the [org-wide contribution guide](https://github.com/containerd/project/blob/main/CONTRIBUTING.md). They cover change scope, tests, license headers, commit sign-offs, and AI attribution. + +For AI-assisted work, follow the org guide's [Coding Agent Usage](https://github.com/containerd/project/blob/main/CONTRIBUTING.md#coding-agent-usage) policy and the repository's [submission requirements](CONTRIBUTING.md#automated-and-ai-generated-contributions). The human contributor reviews all content before submission and writes replies to review comments and issue discussions. Automated PR creation requires prior maintainer approval. + +- Before adding a capability, check [SCOPE.md](SCOPE.md). Its allow-list governs features and components. +- Before adding packages or source files, read [Where to put packages](CONTRIBUTING.md#where-to-put-packages). +- Before changing a public API or protobuf definition, read [Public API Stability](RELEASES.md#public-api-stability). +- Before changing daemon configuration, read [Daemon Configuration](RELEASES.md#daemon-configuration) for compatibility and migration requirements. + +When requirements leave behavior or API names ambiguous, resolve them with the human contributor before implementing the change. + +## Build and validation + +- **Builds and dependencies:** read [BUILDING.md](BUILDING.md) for prerequisites, binary targets, build tags, and vendoring. Regenerate `vendor/` with `make vendor`; never hand-edit vendored files. +- **Protobuf changes:** follow [Updating protobuf files](CONTRIBUTING.md#updating-protobuf-files) to regenerate code and check formatting. Never hand-edit generated protobuf code. +- **Lint:** run `make check` with the tools from [Setting up your local environment](CONTRIBUTING.md#setting-up-your-local-environment). If prerequisites are unavailable, report the blocker. +- **Tests:** use [Testing containerd](BUILDING.md#testing-containerd) to select the suite and privileges needed for the changed behavior. Check for skipped tests before reporting coverage. For CRI changes, also read [CRI Plugin Testing Guide](docs/cri/testing.md). + +Run `make clean-test` only on a dedicated test host: it kills every `containerd` and `runc` process and removes runtime state. + +Fix failing checks at the cause, or explain to the human contributor why the check is wrong. Never delete or weaken tests, add `//nolint`, or bypass a check just to make CI pass. + +## Subsystem context + +Read the relevant docs before changing a subsystem: + +| Area | Reference | +| ----------------------------------------- | ------------------------------------------------ | +| Plugin registration and dependencies | [Plugin model](docs/PLUGINS.md) | +| Task execution and shim lifecycle | [Runtime v2](docs/runtime-v2.md) | +| Sandbox controllers | [Sandbox API](docs/sandbox-api.md) | +| CRI requests and kubelet integration | [CRI architecture](docs/cri/architecture.md) | +| Content, snapshots, and their labels | [Content flow](docs/content-flow.md) | +| Resource retention and garbage collection | [Garbage collection](docs/garbage-collection.md) | +| Namespace propagation through context | [Namespaces](docs/namespaces.md) | +| Daemon-side image transfers | [Transfer service](docs/transfer.md) | + +## Security findings + +Before scanning for security issues, evaluating a suspected vulnerability, or drafting a security report, read all three: + +- [Threat model](docs/security/THREAT_MODEL.md): trust boundaries, trusted components, and security exclusions. +- [Triage guide](docs/security/TRIAGE_GUIDE.md): required evidence and finding classifications. +- [Operator baseline](docs/security/OPERATOR_GUIDELINES.md#1-baseline-security-requirements): deployment assumptions used in triage. + +Apply their scope and evidence requirements before calling a finding a vulnerability. Findings outside the threat model are not vulnerabilities. + +Raise suspected non-public vulnerabilities privately with the human contributor, who decides whether to use the [Security Advisories portal](https://github.com/containerd/containerd/security). Never disclose them in issues, PRs, commits, review comments, or public chat; containerd channels in the CNCF Slack are public. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file