Development workflow

The day-to-day cycle for working in this repo. Aimed at engineers — process details for the wider community live in the official docs.

Branches

• master is the integration branch for the next minor release.
• v3.<minor> branches are the maintenance branches for shipped versions. Bug fixes land here first and are then merged forward (v3.6 → v3.7 → master).
• The merge direction matters because Traefik supports the previous minor version. git log --oneline | head on master shows entries like Merge branch v3.7 into master.

For features: branch from master. For bug fixes: branch from the oldest version branch that needs the fix.

Inner loop

A typical fast iteration loop:

# Edit code
go build ./...                # quick compile sanity check
make lint                     # golangci-lint
go test ./pkg/... -run TestName -count=1   # focused unit test

The full make test-unit is reasonably fast because everything network-related sits in integration/. Run focused tests during development and the full suite before opening a PR.

For UI work:

cd webui
yarn install
yarn dev      # Vite dev server, talks to a running Traefik
yarn test     # vitest
yarn build    # webui/static is what gets embedded

Commits and PRs

The history shows the conventions used by maintainers:

• Commit subjects are imperative and short: Add limit-connections support, Use a metamodel to generate dynamic configuration in ingress-nginx, Prepare release v3.7.0-rc.3.
• Squash on merge is the norm, so each PR usually becomes one commit on master.
• Co-authorship is expressed via standard Git trailers when used.

PR descriptions follow the template in .github/. The triage labels (kind/bug, kind/enhancement, priority/*, area/*, status/*) are documented in the contributors-guide repo.

Generated files and go generate

Several files are regenerated rather than hand-edited. Run the corresponding make target whenever you modify the relevant source:

Generator	Trigger	Output
go generate ./... (root generate.go)	Configuration field changes	docs/content/reference/static-configuration/{cli,env,file,kv}.md and similar
make generate-crd	CRD type changes	pkg/provider/kubernetes/crd/generated/, deepcopy files (zz_generated.deepcopy.go)
make generate-genconf	Dynamic-config type changes	Updated genconf package consumers
Dashboard build (make generate-webui)	UI changes	webui/static/ (embedded by webui/embed.go)

make generate calls go generate from the repo root.

Release flow

Tags follow Semantic Versioning. The history shows the cadence:

• vX.Y.0-ea.N — early-access pre-releases for testing.
• vX.Y.0-rc.N — release candidates.
• vX.Y.Z — patch releases on a maintenance branch.

Release tagging is handled by maintainers via .github/workflows/release.yaml and goreleaser (.goreleaser.yml.tmpl). Contributors do not tag.

CHANGELOG and migration notes

CHANGELOG.md is hand-curated per release. PRs do not update it directly — release captains roll up merged PRs into the changelog at release time.

Migration notes for breaking changes live in docs/content/migration/ and on the website. If your PR contains a migration concern, flag it in the PR description so it can be added.

Working with vendored or missing-tag dependencies

go.mod contains a few replacements and pseudo-version pins:

• github.com/abbot/go-http-auth v0.0.0-00010101000000-000000000000 // No tag on the repo.
• github.com/containous/alice v0.0.0-20181107144136-d83ebdd94cbd // No tag on the repo.

These are intentional. If you upgrade them, follow the conventions in the existing comments.

Code review expectations

From the visible commit history and the maintainers guide, expectations are:

• New providers, middlewares, and load-balancing strategies require integration tests, not just unit tests.
• Schema changes (anything in pkg/config/static or pkg/config/dynamic) require the corresponding generated documentation to be updated.
• Public exported APIs are not stable — Traefik is shipped as a binary, so internal refactors are routine. Mind the import boundaries between pkg/server, pkg/provider, and pkg/middlewares.
• Backwards-compatibility is taken seriously for configuration. New fields must be optional with a sensible zero value; deprecations get the // Deprecated: doc comment (see Core.DefaultRuleSyntax).