# 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](code_of_conduct.md) 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:

```sh
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:

```sh
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:

```sh
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:

```sh
make build
```

Run verifiers:

```sh
make verifiers
```

Run unit tests:

```sh
make test
```

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

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

Run a focused test:

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

Run IAM-specific tests:

```sh
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:

```sh
go generate ./...
make check-gen
```

Generated files must be committed with the source change.

## Dependencies

Buckit uses Go modules.

Add or update a dependency:

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

Remove a dependency by deleting the imports and then running:

```sh
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.