buckit/CONTRIBUTING.md

Buckit Contribution Guide

Buckit welcomes contributions that improve the server, documentation, tests, packaging, and operator experience.

Join the Buckit community on Discord if you want to discuss a change before opening a pull request: https://discord.gg/8BDBVDPqp.

Please follow the Code of Conduct when participating in project spaces.

Development Setup

Buckit requires Go 1.25 or newer. If Go is not installed, download and install it from the official Go installation page: https://go.dev/doc/install.

Clone the repository and build the server:

git clone https://github.com/buckit-io/buckit.git
cd buckit
make build
./buckit --version

The built server binary is ./buckit.

Contribution Workflow

1. Fork https://github.com/buckit-io/buckit.
2. Clone your fork locally.
3. Add the upstream repository as a remote.
4. Create a branch for your change.
5. Make the smallest coherent change that solves the issue.
6. Add or update tests and documentation as needed.
7. Run the relevant verification commands.
8. Open a pull request.

Example:

git clone https://github.com/YOUR_GITHUB_USER/buckit.git
cd buckit
git remote add upstream https://github.com/buckit-io/buckit.git
git fetch upstream
git checkout -b my-change upstream/master

Keep your branch current with upstream:

git fetch upstream
git rebase upstream/master

Verification

Run the smallest useful test set while developing, then run the full relevant checks before opening a pull request.

Build:

make build

Run verifiers:

make verifiers

Run unit tests:

make test

Manual go test commands must include the kqueue build tag. Use the dev tag for tests that require it:

CGO_ENABLED=0 go test -v -tags kqueue,dev ./...

Run a focused test:

CGO_ENABLED=0 go test -v -tags kqueue,dev -run TestFoo ./cmd/

Run IAM-specific tests:

MINIO_API_REQUESTS_MAX=10000 CGO_ENABLED=0 go test -timeout 15m -tags kqueue,dev -v -run TestIAM* ./cmd

Generated Code

Files ending in _gen.go are generated by msgp. Files ending in _string.go are generated by stringer.

After changing source types or annotations used by generated code, run:

go generate ./...
make check-gen

Generated files must be committed with the source change.

Dependencies

Buckit uses Go modules.

Add or update a dependency:

go get example.com/module@version
go mod tidy

Remove a dependency by deleting the imports and then running:

go mod tidy

Commit go.mod and go.sum changes when they are part of your change.

Coding Guidelines

• Follow standard Go style and the guidance in https://go.dev/wiki/CodeReviewComments.
• Keep changes focused. Avoid mixing refactors, formatting-only edits, and behavior changes in one pull request.
• Preserve existing storage formats and compatibility unless the change explicitly migrates them.
• Include tests for behavior changes and regression fixes.
• Run gofumpt and goimports formatting through the configured lint flow.

Pull Requests

Use clear commit messages and pull request descriptions. Explain:

• What changed.
• Why the change is needed.
• How it was tested.
• Any compatibility or migration impact.

Pull requests are reviewed on GitHub. Address review feedback with follow-up commits; maintainers may squash commits when merging.

License

By contributing to Buckit, you agree that your contribution is licensed under the repository's AGPLv3 license.