mirror of
https://github.com/buckit-io/buckit.git
synced 2026-09-23 11:03:20 +00:00
abuckit
158 lines
3.5 KiB
Markdown
158 lines
3.5 KiB
Markdown
# 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.
|