Development workflow

The day-to-day cycle for working on Caddy: clone, branch, change, test, PR. The full process is in .github/CONTRIBUTING.md; this page focuses on what is unique to this codebase.

Branching

Default branch is master. CI runs on pushes to master and to maintenance branches matching 2.* (.github/workflows/ci.yml). Feature work happens on topic branches; PRs target master unless you are backporting.

Release tags follow v2.<minor>.<patch> (e.g. v2.11.2, v2.10.0-beta.4). auto-release-pr.yml and release-proposal.yml automate the bookkeeping for cutting a release.

Building

cd cmd/caddy
go build

The default build at cmd/caddy/main.go imports the standard module set via:

import _ "github.com/caddyserver/caddy/v2/modules/standard"

If you are working on a plugin and need it linked into a custom binary, use xcaddy:

xcaddy build --with github.com/your/plugin

Tests

Run the full unit suite with the race detector before pushing — that's what CI does:

go test -race -short ./...

For a single subsystem:

go test ./modules/caddyhttp/reverseproxy/...
go test ./caddyconfig/caddyfile/...

Integration tests use a separate harness; see Testing.

Lint

golangci-lint run --timeout 10m

The config in .golangci.yml enables a small fixed set of linters with project-specific exclusions. Don't add new top-level lint disables without discussion.

Commits and PR style

• One logical change per PR. The reviewers are explicit about preferring small focused diffs.
• Commit messages follow conventional-commit-ish style (feat:, fix:, chore:, caddyhttp:, tls:, …) and end with (#NNNN) referencing the PR number when squash-merged.
• The PR template at .github/pull_request_template.md asks you to confirm the change is documented if it affects user-visible behavior.

CLA

Every contributor must sign the Contributor License Agreement once. The CLA bot blocks merges until that's done. Per AGENTS.md, the CLA must be signed by the human user, not by an AI agent.

Cross-platform

The CI matrix runs on Ubuntu, macOS, and Windows. Any code that touches the filesystem, sockets, or process management should account for Windows (look for *_windows.go siblings):

• filepath_windows.go, filepath.go
• service_windows.go, sigtrap_*.go
• listen_reuseUnixSocket_windows.go (Windows can't actually reuse Unix sockets)

The s390x-test job in ci.yml tests on IBM Z over SSH; it's marked continue-on-error because the VM is occasionally unreachable.

Where to ask

• Bugs and feature requests: https://github.com/caddyserver/caddy/issues (use the issue templates in .github/ISSUE_TEMPLATE/).
• Support questions: https://caddy.community (the issue tracker is not a support forum).
• Security disclosures: see .github/SECURITY.md.

Related pages

• Testing
• Debugging
• Tooling
• Patterns and conventions