mirror of
https://github.com/podman-container-tools/podman.git
synced 2026-08-05 00:15:44 +00:00
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:
parent
27fde9c84a
commit
e880d0550d
1 changed files with 7 additions and 9 deletions
16
AGENTS.md
16
AGENTS.md
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue