Contributing

Armada welcomes contributions of all kinds — bug reports, feature requests, documentation improvements, and code changes. If you would like to get involved, feel free to reach out in GitHub Discussions, raise an issue, or open a pull request.

Request For Comments

For most of the changes, the normal pull request workflow is sufficient. However, some significant changes should go through a design process and consensus must be reached among maintainers. For this purpose, we have the Request For Comments process. RFC should be drafted for example when:

introducing a new feature or an API,
redesigning internals in a major way,
or considering breaking changes.

When drafting an RFC, follow the template and create a pull request to start the discussion. The pull request should be tagged with the label proposal.

Development prerequisites

Go >= 1.22
Protocol Buffer compiler >= 3
Go Protocol Buffer compiler plugin -- go install google.golang.org/protobuf/cmd/protoc-gen-go
Go Vitess Protocol Buffers compiler -- go install github.com/planetscale/vtprotobuf/cmd/protoc-gen-go-vtproto
Go gRPC generator Protocol Buffer compiler plugin -- go install google.golang.org/grpc/cmd/protoc-gen-go-grpc
Go documentation Protocol Buffer compiler plugin -- go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc

Testing prerequisites

Docker and kind — used for manual integration testing
gRPC curl — useful for testing the gRPC API interactively

Development Workflow

Build

# Build only the armada binary (fast iteration)
make armada

# Regenerate protobuf outputs and build the binary (full build)
make build

# Regenerate protobuf outputs only
make proto

Test

# Run the full test suite with race detection and coverage
make test

# Run tests for a single package
go test ./storage/table/...

# Run a single named test
go test ./storage/table/... -run '^TestTableManager$'

Lint

# Run the linter (runs make proto first)
make check

Run locally

# Start a single-node leader cluster in development mode
make run

# Start a follower connected to the local leader (requires make run to be running)
make run-follower

Running Documentation Site Locally

This documentation site is powered by Jekyll. First, install Jekyll and bundler:

gem install bundler jekyll

Then, install the necessary gems:

cd ./docs
bundle install

Last, run Jekyll in the root of the repository:

make serve-docs