mirror of
https://github.com/containers/podman.git
synced 2026-02-05 06:45:31 +01:00
Initial draft of AGENTS.md
* Add support for https://agents.md/ [NO TESTS NEEDED] Signed-off-by: Jhon Honce <jhonce@redhat.com> See: [AGENTS.md](https://agents.md/)
This commit is contained in:
Jhon Honce
154
AGENTS.md
Normal file
154
AGENTS.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# AI Agent Guide for Podman Development
|
||||
|
||||
|
||||
|
||||
Quick reference guide for AI agents assisting with Podman development.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Podman** is a daemonless container engine with Docker-compatible CLI, rootless support, and native pod management.
|
||||
|
||||
**Key Technologies**: [Cobra](https://github.com/spf13/cobra), [containers/image](https://github.com/containers/image), [containers/storage](https://github.com/containers/storage), [crun](https://github.com/containers/crun), [Go](https://golang.org), [Netavark](https://github.com/containers/netavark), [runc](https://github.com/opencontainers/runc)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Build and test
|
||||
make binaries # Build all binaries
|
||||
make validatepr # Format, lint, and validate (required for PRs)
|
||||
make localintegration # Run integration tests
|
||||
make localsystem # Run system tests
|
||||
|
||||
# Development tools
|
||||
make install.tools # Install linters and dev tools
|
||||
```
|
||||
|
||||
## Codebase Structure
|
||||
|
||||
```text
|
||||
podman/
|
||||
├── cmd/podman/ # CLI commands (Cobra framework)
|
||||
├── libpod/ # Core container/pod management (Linux only)
|
||||
├── pkg/
|
||||
│ ├── api/ # REST API server
|
||||
│ ├── bindings/ # HTTP client (stable API)
|
||||
│ ├── domain/ # Business logic layer
|
||||
│ │ ├── entities/ # Interfaces and data structures
|
||||
│ │ ├── infra/abi/ # Local implementation
|
||||
│ │ └── infra/tunnel/ # Remote implementation
|
||||
│ └── specgen/ # Container/pod specifications
|
||||
├── test/e2e/ # Integration tests (Ginkgo)
|
||||
├── test/system/ # System tests (BATS)
|
||||
├── docs/source/markdown/ # Man pages
|
||||
└── vendor/ # Vendored dependencies (DO NOT EDIT)
|
||||
```
|
||||
|
||||
## Development Patterns
|
||||
|
||||
### CLI Command Pattern
|
||||
|
||||
```go
|
||||
// cmd/podman/command.go
|
||||
var commandCmd = &cobra.Command{
|
||||
Use: "command [options] args",
|
||||
RunE: commandRun,
|
||||
}
|
||||
|
||||
func commandRun(cmd *cobra.Command, args []string) error {
|
||||
return registry.ContainerEngine().Command(registry.GetContext(), options)
|
||||
}
|
||||
```
|
||||
|
||||
### Domain Layer Pattern
|
||||
|
||||
```go
|
||||
// pkg/domain/infra/abi/command.go (local)
|
||||
func (ic *ContainerEngine) Command(ctx context.Context, options entities.CommandOptions) error {
|
||||
return ic.Libpod.Command(options) // Direct libpod call
|
||||
}
|
||||
|
||||
// pkg/domain/infra/tunnel/command.go (remote)
|
||||
func (ic *ContainerEngine) Command(ctx context.Context, options entities.CommandOptions) error {
|
||||
return bindings.Command(ic.ClientCtx, options) // HTTP API call
|
||||
}
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Integration Tests ([Ginkgo](https://github.com/onsi/ginkgo))
|
||||
|
||||
```go
|
||||
It("should work correctly", func() {
|
||||
session := podmanTest.Podman([]string{"command", "args"})
|
||||
session.WaitWithDefaultTimeout()
|
||||
Expect(session).Should(Exit(0))
|
||||
})
|
||||
```
|
||||
|
||||
### System Tests ([BATS](https://github.com/bats-core/bats-core))
|
||||
|
||||
```bash
|
||||
@test "podman command functionality" {
|
||||
run_podman command --option value
|
||||
is "$output" "expected output" "description"
|
||||
}
|
||||
```
|
||||
|
||||
## Code Standards
|
||||
|
||||
**Official Documentation**: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
- **Formatter**: `gofumpt` (via `golangci-lint`, configured in `.golangci.yml`)
|
||||
- **Validation**: All PRs must pass `make validatepr`
|
||||
- **Commits**: Must be signed (`git commit -s`) and follow [DCO](CONTRIBUTING.md#sign-your-prs)
|
||||
- **Reviews**: Two approvals required for merge
|
||||
|
||||
## Key Libraries
|
||||
|
||||
- **[containers/buildah](https://github.com/containers/buildah)**: Image building
|
||||
- **[containers/common](https://github.com/containers/common)**: Shared utilities
|
||||
- **[containers/image](https://github.com/containers/image)**: Image management
|
||||
- **[containers/storage](https://github.com/containers/storage)**: Container and image storage
|
||||
- **[gorilla/mux](https://github.com/gorilla/mux)**: HTTP router and URL matcher for REST API
|
||||
- **[gorilla/schema](https://github.com/gorilla/schema)**: Form data to struct conversion
|
||||
- **[netavark](https://github.com/containers/netavark)**: Network management
|
||||
|
||||
## 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
|
||||
|
||||
## Essential Commands
|
||||
|
||||
```bash
|
||||
# Analysis
|
||||
go list -tags "$BUILDTAGS" -f '{{.Deps}}' ./cmd/podman # Dependencies
|
||||
grep -r "pattern" --include="*.go" . # Find patterns
|
||||
|
||||
# Testing
|
||||
make localintegration FOCUS_FILE=your_test.go # Single test file
|
||||
make localintegration FOCUS="test description" # Single test
|
||||
PODMAN_TEST_SKIP_CLEANUP=1 make localintegration # Debug mode
|
||||
|
||||
# Validation
|
||||
make validatepr # Full validation
|
||||
make lint # Linting only
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[CONTRIBUTING.md](CONTRIBUTING.md)**: Development guidelines
|
||||
- **[DISTRO_PACKAGE.md](DISTRO_PACKAGE.md)**: Packaging guidelines for distributors
|
||||
- **[docs/CODE_STRUCTURE.md](docs/CODE_STRUCTURE.md)**: Detailed codebase structure
|
||||
- **[docs/tutorials/](docs/tutorials/)**: Step-by-step guides and tutorials
|
||||
- **[GOVERNANCE.md](GOVERNANCE.md)**: Project organization and contributor roles
|
||||
- **[LICENSE](LICENSE)**: Apache 2.0 license terms
|
||||
- **[README.md](README.md)**: Project overview
|
||||
- **[RELEASE_PROCESS.md](RELEASE_PROCESS.md)**: Release workflow (maintainers only)
|
||||
- **[rootless.md](rootless.md)**: Rootless limitations and troubleshooting
|
||||
- **[test/README.md](test/README.md)**: Testing framework details
|
||||
|
||||
For comprehensive information, refer to the official documentation and recent commits in the [Podman repository](https://github.com/containers/podman).
|
||||
Reference in New Issue
Block a user