How to contribute

Note: README.md says the public community repository is no longer actively maintained. The contribution process below still describes how the project has historically accepted external work, and it remains the model for any internal forks or vendor patches.

The canonical guide is CONTRIBUTING.md. This page expands it with the conventions a contributor needs in their first day.

Pickup a piece of work

• Bug fixes. Reproduce against master, then narrow to the smallest test that exercises the bug. Run make test to confirm the test suite still passes after the fix.
• Features. Behaviour change is best discussed first on the MinIO Slack. Internal features are typically shipped behind a config knob in internal/config/<area>/.
• Docs. Operational and tutorial docs live under docs/. Many of those tutorial docs double as test scripts that are wired into Makefile.

The PR process

CONTRIBUTING.md lays out the standard fork → branch → PR flow. Specific expectations:

• One logical change per PR. Squash to a single commit with a descriptive message before merging. The commit message should explain why, not just what. Many merged PRs follow the Chris Beams style.
• Add or update tests. Behaviour changes need either a Go unit test (*_test.go) or, when shell-driven, an end-to-end script under buildscripts/ or docs/. The test-target table in Makefile shows the buckets.
• Run make verifiers before pushing. This invokes lint (golangci-lint, config in .golangci.yml), the typo checker (.typos.toml), go mod tidy, and go generate ./.... The check-gen target fails the PR if any _gen.go files are dirty.
• Run make test and make build. They both run as part of the CI workflows in .github/workflows/.

Definition of done

A change is considered done when:

1. make verifiers passes locally.
2. make test passes.
3. The relevant make test-* integration scripts pass for the area you touched (e.g. make test-replication for a replication change).
4. A reviewer has approved the PR.
5. Generated code (*_gen.go, go.sum) is committed alongside the change that produced it. CI explicitly checks for this in Makefile:check-gen.

What "good" looks like

The codebase is opinionated. Read Patterns and conventions before writing your first handler or storage change. The TL;DR:

• Errors flow up unchanged or are wrapped with context; they are never swallowed.
• Locks are explicit. Every object operation acquires a namespace-lock first.
• Generated code is committed. Don't hand-edit *_gen.go; regenerate with go generate.
• No new global state without a reason. cmd/globals.go already collects most of the global handles; new ones go through review.

Where to start reading

• cmd/server-main.go — the boot sequence, every CLI flag.
• cmd/api-router.go and cmd/admin-router.go — every HTTP route.
• cmd/object-api-interface.go — the central ObjectLayer interface.
• cmd/erasure-server-pool.go — the runtime that implements ObjectLayer.
• internal/config/config.go — how every subsystem registers configuration.

Links

• Development workflow
• Testing
• Debugging
• Patterns and conventions
• Tooling