Skip to content

index.md

Latest commit

 

History

History
198 lines (144 loc) · 7.9 KB

index.md

File metadata and controls

198 lines (144 loc) · 7.9 KB
Raw
title Contributing
description Docker Agent is open source. Here's how to set up your development environment and contribute.
keywords docker agent, ai agents, community, contributing
weight 10
canonical https://docs.docker.com/ai/docker-agent/community/contributing/

Docker Agent is open source. Here's how to set up your development environment and contribute.

Development Setup

Prerequisites

Note

Platform Support

macOS and Linux are fully supported for development. On Windows, use task build-local to build via Docker.

Build from Source

# Clone and build
git clone https://github.com/docker/docker-agent.git
cd docker-agent
task build

# Set API keys
export OPENAI_API_KEY=your_key_here
export ANTHROPIC_API_KEY=your_key_here

# Run an example
./bin/docker-agent run examples/code.yaml

Development Commands

Command Description
task build Build the binary to ./bin/docker-agent
task test Run all tests (clears API keys for determinism)
task lint Run golangci-lint, custom checks, and module tidiness checks
task format Format code
task dev Run lint, test, and build in parallel
task build-local Build for local platform via Docker
task cross Cross-platform builds (all architectures)

Debugging TUI Tests

The headless TUI harness can save each captured frame for inspection:

mkdir -p .cache/tui-test
go test -count=1 -v -artifacts -outputdir="$PWD/.cache/tui-test" ./e2e/tui -tuitest.frames

-tuitest.frames writes numbered text files in a separate frames-* directory for each driver, under the test's testing.TB.ArtifactDir(). The test log prints the exact path. -artifacts retains these directories after the tests finish; without it, dumps are temporary and removed during test cleanup. Use -count=1 to capture fresh frames rather than reuse a cached test result.

With the command above, retained dumps are under .cache/tui-test/_artifacts/. For CI jobs that enable frame dumping, upload this directory even when tests fail. Dumps are no longer written alongside golden files in testdata/frames; -tuitest.update still updates golden files in testdata/.

For an approximate live view instead, use go test -v ./e2e/tui -tuitest.live.

Dogfooding

Use Docker Agent to work on Docker Agent! The project includes a specialized developer agent:

cd docker-agent
docker agent run ./golang_developer.yaml

This agent is an expert Go developer that understands the Docker Agent codebase. Ask it questions, request fixes, or have it implement features.

Core Concepts

  • Root Agent — Main entry point that coordinates the system
  • Sub-Agents — Specialized agents for specific domains
  • Tools — External capabilities via MCP
  • Models — AI provider configurations

Code Style

The project uses golangci-lint with strict rules. As long as task lint passes, the code is stylistically acceptable.

Key conventions:

  • Use fmt.Errorf("context: %w", err) for error wrapping
  • Always pass context.Context as the first parameter
  • Use slog for structured logging
  • Use functional options pattern for constructors
  • In tests: use t.Context(), t.TempDir(), t.Setenv(), and t.Parallel()

Project-specific lint rules

task lint runs the custom cops in lint/. Lint/FieldsSeq flags strings.Fields slices used only for one value-only range, including loops with an empty-input fallback. Use strings.FieldsSeq, evaluate its input at the original location, and track whether any word was yielded when preserving that fallback. Indexing, repeated traversal, capacity/count uses, mutable byte inputs, and FieldsFunc callbacks are intentionally excluded.

Lint/PointerHelper recommends native new expressions for AWS scalar pointer helpers. Preserve explicit numeric conversions; slice/map and dereference helpers are not replacements for new.

Lint/ReflectFields covers paired reflect.Value.Field(i) and Value.Type().Field(i) loops that the upstream iterator analyzer misses. It excludes receiver mutation/escape, unrelated index uses, and unsafe callbacks.

Lint/StdlibUUID recommends stdlib UUIDs for random strings and canonical literal-to-string conversions. It preserves UUIDv5 and compatibility parsers, and skips recommendations when production or test code configures Google UUID randomness. General parsers and values exposing the Google UUID type are excluded.

Lint/URLClone recommends url.URL.Clone for equivalent nil-safe deep copies or copies guarded by User == nil. General shallow copies are excluded because Clone also copies userinfo.

Lint/JSONMarshalWrite flags a single buffered encoding followed by newline trimming. Review the suggested jsonv2.MarshalWrite migration with v1 defaults, explicit HTML escaping, unchanged evaluation order, and discarded partial output on error. Streaming encoders and indentation are excluded.

Lint/BenchmarkLoop covers simple ResetTimer/b.N loops, including sub-benchmarks and test-only packages. Review measurement and compiler effects before adopting b.Loop; parallel, timer-sensitive, and escaping benchmark handles are excluded. These cops report suggestions, never automatic rewrites. The non-benchmark modernization cops inspect production packages; the UUID randomness guard additionally reads tests.

Test output/artifact lifetimes and in-memory HTTP compatibility require review; there are no blanket rules for t.Output, ArtifactDir, or NewTestServer.

Opening Issues

File issues on the GitHub issue tracker. Please:

Note

See also

Troubleshooting — Common issues and debug mode. Telemetry — What data is collected and how to opt out.

  • Use the included issue template
  • Search for existing issues before creating new ones
  • Only use issues for bugs and feature requests (not support)

Submitting Pull Requests

  1. Fork the repository and create a branch for your changes
  2. Write your code following the style and testing guidelines above
  3. Test your changes: run task lint and task test
  4. Sign off your commits with git commit -s (DCO required)
  5. Open a pull request against the main branch

Tip

Use the dogfooding agent (docker agent run ./golang_developer.yaml) to help write and review your changes before submitting.

Sign Your Work

All contributions require a Developer Certificate of Origin (DCO) sign-off:

# Set the identity used for the sign-off
$ git config user.name "Your Name"
$ git config user.email "your.email@example.com"

# Add a DCO sign-off to this commit
$ git commit -s -m "Your commit message"

-s adds a Signed-off-by trailer; it does not cryptographically sign the commit. To also sign with a GPG or SSH key, configure Git signing and use git commit -S -s.

Community

Find us on Slack for questions and discussions.

Code of Conduct

We want to keep the Docker Agent community welcoming, inclusive, and collaborative. Key guidelines:

  • Be nice — Be courteous, respectful, and polite. No abuse of any kind will be tolerated.
  • Encourage diversity — Make everyone feel welcome regardless of background.
  • Keep it legal — Share only content you own and don't break the law.
  • Stay on topic — Post to the correct channel and avoid off-topic discussions.

The governance for this repository is handled by Docker Inc.