Development

This page describes the developer workflow for working in the Arcentra repository. All commands assume you are at the root of the arcentra checkout.

Toolchain

Go 1.25 or later (matches go.mod).
Buf — Protobuf and gRPC code generation. make buf-install installs it on demand.
Wire — compile-time dependency injection. make wire-install installs it on demand.
golangci-lint v2 — installed automatically into bin/ by make lint.
staticcheck (optional) — make staticcheck installs and runs it.
addlicense (optional) — make addlicense adds Apache 2.0 headers to Go files.
Docker (optional) — required for make docker-build and make docker-buildx.

Make targets

make help prints the full target list. The targets you reach for most often are:

Target	What it does
`make deps`	`go mod tidy` and `go mod verify`
`make codegen`	Run all code generators (Buf + Wire for both binaries)
`make buf`	Generate gRPC/protobuf code
`make wire TARGET=arcentra`	Generate Wire bindings for the control plane
`make wire TARGET=arcentra-agent`	Generate Wire bindings for the agent
`make build TARGET=<name>`	Build a binary; `<name>` matches a `cmd/` subdirectory
`make build-target TARGET=<name>`	Release build with `-trimpath -s -w` (CI/Docker)
`make run`	Run the control plane locally
`make lint`	Install golangci-lint v2 and run linters
`make fmt-check`	Verify formatting (excludes generated files)
`make test`	`go test -race -count=1 ./...`
`make staticcheck`	Run staticcheck across the module
`make docker-build`	Build a Docker image with `docker buildkit`
`make docker-buildx`	Multi-arch (`linux/arm64,linux/amd64`) build and push
`make addlicense`	Add license headers to Go files
`make version`	Print version, branch, commit, and build time
`make version-tag`	Create and annotate `vX.Y.Z.W` git tag

The repository carries two binaries by default: arcentra (control plane) and arcentra-agent. Any directory inside cmd/ can be built with make build TARGET=<dirname>.

Code generation

Two generators are wired into the build:

Buf generates Go message and gRPC service code under api/<service>/v1.
Wire generates dependency-injection wiring (wire_gen.go) under cmd/arcentra/ and cmd/arcentra-agent/.

Run make codegen after editing any .proto file or any wire.go file.

Testing

make test

This runs the full Go test suite with the race detector enabled. For a single package, run go test -race ./internal/path/... directly.

Configuration during development

The default configuration files under conf.d/ are tailored for local development:

conf.d/config.toml — control plane.
conf.d/agent.toml — agent.
conf.d/plugins.toml — plugins and builtins.

make run starts the control plane against these defaults; you can also run go run ./cmd/arcentra -conf <path> and go run ./cmd/arcentra-agent -conf <path> directly. See Configuration for a reference of every section.

Versioning and releases

Arcentra uses a four-part YY.Major.Minor.Patch version scheme:

YY — last two digits of the year (25 for 2025, 26 for 2026).
Major — incremented for architecture changes or breaking APIs.
Minor — incremented for new, backward-compatible features.
Patch — incremented for bug fixes and small adjustments.

Examples:

0.0.0  -> initial release in 2025
0.0.1  -> bug fix
0.1.0  -> new feature (backward compatible)
1.0.0  -> major change
0.0.0  -> first release of 2026

Choosing the version at build time

The Makefile resolves the version in this order:

The VERSION environment variable.
A VERSION file at the repository root.
An exact-match git tag (with the leading v stripped).
Fallback to <current-2-digit-year>.0.0.0.

# explicit
VERSION=25.1.2.3 make build TARGET=arcentra

# via VERSION file
echo -n "25.1.2.3" > VERSION
make build TARGET=arcentra

Tagging a release

export VERSION=25.1.2.3
make version-tag
git push origin v$VERSION

Tags follow the vYY.Major.Minor.Patch convention.

Reading the version from Go

import "github.com/arcentrix/arcentra/pkg/version"

v := version.GetVersion()
fmt.Println(v.Version)

parsed, err := version.GetParsedVersion()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("year=20%02d major=%d minor=%d patch=%d\n",
    parsed.Year, parsed.Major, parsed.Minor, parsed.Patch)

Contributing

Read CONTRIBUTING.md for the full process. In short:

Fork and branch from main.
Run make codegen, make lint, and make test locally before opening a PR.
Add or update documentation in this site for any user-visible change.
Reference the related issue and follow the project’s commit and PR conventions.

Security issues should be reported privately as described in SECURITY.md.

Getting started

Concepts

Operate

Toolchain

Make targets

Code generation

Testing

Configuration during development

Versioning and releases

Choosing the version at build time

Tagging a release

Reading the version from Go

Contributing

​Toolchain

​Make targets

​Code generation

​Testing

​Configuration during development

​Versioning and releases

​Choosing the version at build time

​Tagging a release

​Reading the version from Go

​Contributing

Toolchain

Make targets

Code generation

Testing

Configuration during development

Versioning and releases

Choosing the version at build time

Tagging a release

Reading the version from Go

Contributing