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. 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. - **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. - **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. - **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**: 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). - **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).
- **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.
## Project Overview ## Project Overview
@ -131,11 +130,10 @@ It("should work correctly", func() {
## Common Pitfalls for AI Agents ## Common Pitfalls for AI Agents
1. **Never edit `vendor/`** - Use `go get` then `make vendor` 1. **Platform awareness** - Consider Linux/Windows/macOS differences
2. **Platform awareness** - Consider Linux/Windows/macOS differences 2. **Rootless vs root** - Many behaviors differ between modes
3. **Rootless vs root** - Many behaviors differ between modes 3. **Remote vs local** - Different code paths (`abi` vs `tunnel`)
4. **Remote vs local** - Different code paths (`abi` vs `tunnel`) 4. **Test cleanup** - Always clean up test artifacts
5. **Test cleanup** - Always clean up test artifacts
## Essential Commands ## Essential Commands