AGENTS.md: address review feedback from PR #28593

- Replace absolute GitHub links with relative paths
- Reword "Scope and neighbors" as "Vendored dependencies" focusing
  on the vendor/ boundary (mheon)
- Remove redundant CONTRIBUTING.md reference from Quality bar (mheon)
- Remove "Community stance" bullet as context-window filler (mheon)
- Deduplicate vendor/ pitfall already covered in Persona section

Assisted-by: Cursor:claude-opus-4-6
Signed-off-by: Jhon Honce <jhonce@redhat.com>
This commit is contained in:
Jhon Honce 2026-05-03 17:16:18 -07:00
parent 27fde9c84a
commit e880d0550d

View file

@ -6,13 +6,12 @@
This guide is for AI coding assistants (for example Claude, ChatGPT, Copilot). Use it for context on codebase layout, development patterns, testing, pitfalls, and upstream expectations when helping **contributors to [containers/podman](https://github.com/containers/podman)**—people writing patches, tests, and in-tree docs, triaging or fixing issues, and preparing pull requests.
When assisting them, align with how upstream describes the project and how contributors are expected to work. Source material: [README.md](https://github.com/containers/podman/blob/main/README.md), [CONTRIBUTING.md](https://github.com/containers/podman/blob/main/CONTRIBUTING.md), [GOVERNANCE.md](https://github.com/containers/podman/blob/main/GOVERNANCE.md).
When assisting them, align with how upstream describes the project and how contributors are expected to work.
- **Audience**: Assume the user is an **upstream contributor** (or aspiring one), not an end user or downstream packager. Optimize for implementing and reviewing changes in this repository: correct layer (`cmd/` vs `libpod/` vs `pkg/domain/`), tests that match existing frameworks, and merge-ready hygiene. Be direct and technical; skip tutorial and brochure tone unless they are editing tutorials or man pages in-tree.
- **Product mental model (for patch context)**: Podman is **daemonless**; lifecycle logic lives in **libpod**. When touching behavior, remember **Docker-compatible CLI/API** paths versus **Podman-specific** surfaces (pods, Quadlet, advanced REST, `podman machine`). Many fixes must consider **rootless vs root** and **local vs remote** (`pkg/domain/infra/abi` vs `tunnel`) so both paths stay consistent.
- **Scope and neighbors**: When routing work or dependencies, respect upstream boundaries from the README: specialized image transport/signing → [Skopeo](https://github.com/containers/skopeo); Kubernetes **CRI** → [CRI-O](https://github.com/cri-o/cri-o); image build integration → [Buildah](https://github.com/containers/buildah)s Go API. Reference the same stack the project uses: **containers/image**, **containers/storage**, **Netavark** / **aardvark-dns**, **conmon**, OCI runtimes (**crun**, **runc**), **container-libs** (seccomp, hooks) when explaining cross-repo behavior.
- **Quality bar**: Mirror **[CONTRIBUTING.md](https://github.com/containers/podman/blob/main/CONTRIBUTING.md)**: backend/libpod development expects **Linux**; macOS/Windows instructions apply to **clients** and `podman machine`, not the Linux engine. Use the **Makefile** (`make help`, `make binaries`, `make validatepr`); match the **Go** version in `go.mod`; sign commits for **DCO**; expect **two approvals** before merge. **Security** issues use the private process linked from CONTRIBUTING, not public GitHub. AI-assisted contributions must follow **[LLM_POLICY.md](https://github.com/containers/podman/blob/main/LLM_POLICY.md)**. For issues they file upstream, insist on reproducers and full `podman info`; discourage noise (“+1” without new data).
- **Community stance**: Treat collaboration as **CNCF Code of Conduct**governed: constructive review comments, clear rationale in PRs, and respect for triage and maintainer time. Point to GitHub **issues/PRs**, **lists.podman.io**, and [podman.io](https://podman.io) community channels when coordination belongs upstream—not as a substitute for landing tests and validation in their branch.
- **Vendored dependencies**: Most external code Podman depends on (containers/image, containers/storage, containers/buildah, containers/common) is checked into `vendor/`. **Never edit vendored files directly**—use `go get` then `make vendor`. When diagnosing behavior that originates in a vendored library, trace the call but propose fixes in the upstream library repo, not in `vendor/`.
- **Quality bar**: Backend/libpod development expects **Linux**; macOS/Windows instructions apply to **clients** and `podman machine`, not the Linux engine. Use the **Makefile** (`make help`, `make binaries`, `make validatepr`); match the **Go** version in `go.mod`. **Security** issues use the private process linked from CONTRIBUTING, not public GitHub. AI-assisted contributions must follow **[LLM_POLICY.md](LLM_POLICY.md)**. For issues they file upstream, insist on reproducers and full `podman info`; discourage noise ("+1" without new data).
## Project Overview
@ -131,11 +130,10 @@ It("should work correctly", func() {
## Common Pitfalls for AI Agents
1. **Never edit `vendor/`** - Use `go get` then `make vendor`
2. **Platform awareness** - Consider Linux/Windows/macOS differences
3. **Rootless vs root** - Many behaviors differ between modes
4. **Remote vs local** - Different code paths (`abi` vs `tunnel`)
5. **Test cleanup** - Always clean up test artifacts
1. **Platform awareness** - Consider Linux/Windows/macOS differences
2. **Rootless vs root** - Many behaviors differ between modes
3. **Remote vs local** - Different code paths (`abi` vs `tunnel`)
4. **Test cleanup** - Always clean up test artifacts
## Essential Commands