Contributing

Contributions to Hivenet Router are welcome, including bug reports, feature proposals, documentation improvements, tests, and code changes. The repository’s root CONTRIBUTING.md file is the canonical contribution guide. This page summarizes the workflow and provides additional context for common changes. By participating in the project, you agree to follow the Code of conduct.

Report a bug

Share a reproducible problem with the affected version, configuration, and relevant logs.

Propose a feature

Describe the use case and expected behavior before investing in a substantial implementation.

Improve the documentation

Correct stale commands, clarify behavior, improve examples, or add missing troubleshooting guidance.

Open a pull request

Submit a focused change with tests, verification details, and a clear explanation of the problem it solves.

Development requirements

Hivenet Router is one Go module. The current go.mod requires:

Go 1.25.5

Use Go 1.25.5 or a compatible later release. Check the installed version:

go version

Clone the repository:

git clone \
  https://github.com/HivenetOSS/hivenet_router.git

cd hivenet_router

Build the complete module:

go build ./...

Build the router and agent binaries:

mkdir -p bin

go build \
  -o bin/hivenet-router \
  ./cmd/router/

go build \
  -o bin/hivenet-agent \
  ./cmd/agent/

The generated binaries are placed under:

bin/

which is excluded from Git.

Repository structure

The main implementation areas are:

Path	Purpose
`cmd/router/`	Router entry point and process startup
`cmd/agent/`	Agent entry point and process startup
`internal/api/`	HTTP routes, handlers, middleware, and audit behavior
`internal/auth/`	Client, administrator, agent, and quota authentication
`internal/router/`	Agent registry, request processing, forwarding, and queueing
`internal/policy/`	Routing policies, gates, fallback chains, and selection
`internal/agent/`	Agent lifecycle, backend adapters, and request proxying
`internal/storage/`	In-memory and persistent BadgerDB state
`internal/metrics/`	Prometheus metrics and persisted agent history
`internal/provider/`	External provider fallback
`internal/transport/`	gRPC and libp2p transport
`proto/`	Agent-authentication protobuf source and generated Go code
`test/`	Most black-box package tests and shared test utilities
`docs/`	Mintlify documentation source
`scripts/`	Setup, benchmark, load, and comparison scripts

Most tests live under test/ and use external packages such as:

package router_test

This exercises exported behavior without depending on internal implementation details. A small number of focused white-box tests live beside the implementation when they need access to an unexported helper.

Run the tests

Run the complete test suite:

go test ./...

Force a fresh run without cached test results:

go test \
  -count=1 \
  ./...

Run with coverage across the internal and protobuf packages:

go test \
  -coverpkg=./internal/...,./proto \
  ./...

Run one package:

go test \
  ./test/router

Run one test by name:

go test \
  ./test/router \
  -run TestName

Use verbose output while diagnosing a failure:

go test \
  -v \
  ./test/router \
  -run TestName

Add tests with a change

A behavior change should normally include tests covering:

the expected path
invalid input
boundary conditions
failure behavior
relevant precedence rules
regression scenarios

Prefer table-driven tests when several inputs should produce related outcomes:

func TestExample(t *testing.T) {
    cases := []struct {
        name string
        input string
        want string
    }{
        {
            name: "first case",
            input: "value",
            want: "result",
        },
    }

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            got := example(tc.input)

            if got != tc.want {
                t.Fatalf(
                    "example(%q) = %q, want %q",
                    tc.input,
                    got,
                    tc.want,
                )
            }
        })
    }
}

Keep each test focused on behavior that would help a future contributor understand why the case matters. Use a white-box test only when testing an unexported behavior directly is clearer than expanding the production API solely for testing.

Format and check the code

Before opening a pull request, run:

go fmt ./...
go vet ./...
go test ./...
go build ./...

go fmt ./... updates Go source files in place. Review the resulting diff:

git diff

Check for accidental changes:

git status --short

Match the surrounding code’s:

naming
error handling
comment density
logging style
package boundaries
concurrency patterns

Keep the change focused. Move unrelated cleanup or refactoring into a separate pull request.

Update dependencies carefully

After intentionally changing module dependencies:

go mod tidy

Review both:

go.mod
go.sum

Do not run go mod tidy as unrelated cleanup in a pull request that does not change dependencies. A dependency change should explain:

why the dependency is needed
why the selected version is appropriate
whether it changes compatibility or runtime behavior
whether it introduces a security or licensing concern

Regenerate protobuf code

The generated files are:

proto/auth.pb.go
proto/auth_grpc.pb.go

Do not edit them manually. Edit the source definition instead:

proto/auth.proto

Install:

protoc
protoc-gen-go
protoc-gen-go-grpc

Then regenerate:

protoc \
  --go_out=. \
  --go_opt=paths=source_relative \
  --go-grpc_out=. \
  --go-grpc_opt=paths=source_relative \
  proto/auth.proto

Run formatting and tests afterward:

go fmt ./...
go test ./...

Review the generated diff carefully. Generated output can change when contributors use different protobuf compiler or plugin versions. Avoid unrelated generated-file churn.

Do not change only the generated *.pb.go files.Those edits will be overwritten the next time proto/auth.proto is regenerated.

Improve the documentation

Documentation lives under:

docs/

Useful documentation contributions include:

correcting behavior that changed in the implementation
replacing stale commands or defaults
clarifying API and configuration boundaries
documenting edge cases
improving navigation
adding verified troubleshooting steps
fixing broken links
correcting examples that no longer match the code

When editing an existing technical page:

Treat the current implementation as the source of truth.
Preserve exact commands, flags, endpoints, schemas, and units.
Distinguish verified behavior from guidance or interpretation.
Do not add product claims that the repository does not support.
Update related pages when one behavior affects several guides.
Check internal links and sidebar placement.

When documentation and code disagree, verify the relevant implementation before deciding which one needs to change.

Report a bug

Open a GitHub issue and include:

the Hivenet Router release or commit
operating system and deployment method
whether the problem affects the router, agent, or both
inference engine and version
exact model ID and capability
relevant configuration with secrets removed
clear reproduction steps
expected behavior
actual behavior
relevant logs
X-Request-ID when one request demonstrates the problem

A useful report separates:

client behavior
router behavior
agent behavior
inference-backend behavior

This makes it easier to identify the failing layer.

Remove secrets and sensitive data before attaching configuration or logs.Do not include:

client API keys
administrator keys
agent JWT secrets
provider credentials
private prompts
customer data

Propose a feature

Open an issue before beginning a substantial feature. Describe:

the user or operator problem
the intended use case
current behavior
expected behavior
API or configuration changes
persistence implications
authentication and security implications
compatibility concerns
operational trade-offs

A proposal is more useful when it explains the problem rather than presenting one implementation as the only acceptable solution. Discussing the approach first reduces the risk of building a large change that conflicts with the project’s architecture or scope.

Create a branch

Fork the repository, then create a topic branch from the current main branch.

git switch main
git pull --ff-only
git switch -c feat/short-description

Use a prefix that reflects the change:

feat/
fix/
docs/

Examples:

feat/per-model-health-gate
fix/streaming-token-accounting
docs/clarify-agent-addresses

Keep one coherent change on each branch.

Prepare the pull request

Before opening the pull request:

go fmt ./...
go vet ./...
go test ./...
go build ./...

Then update the branch with the latest main when necessary. A useful pull request description explains:

what changed
why the change is needed
how the behavior works
how it was tested
any compatibility or migration impact
any remaining limitation
related issues

For example:

What changed

Added ...

Why

The previous behavior ...

Verification

- go test ./...
- go vet ./...
- manual request against ...

Include screenshots only when they help explain:

documentation rendering
dashboards
user-interface integrations
another visual change

Do not use screenshots as the only evidence for API or routing behavior.

Review feedback

Review may ask for:

clearer behavior boundaries
additional tests
smaller changes
compatibility handling
documentation updates
removal of unrelated refactoring

Respond to feedback directly and update the branch rather than opening a replacement pull request for the same work. When you disagree with a suggestion, explain the technical trade-off and provide supporting evidence.

Report a security issue privately

Do not open a public GitHub issue for a suspected vulnerability.

Email:

support@hivenet.com

Include:

affected component and version
reproduction steps
expected security boundary
observed behavior
potential impact
any temporary mitigation

Do not include production credentials unless the maintainers explicitly request them through an appropriate secure channel. The maintainers will coordinate investigation, remediation, and disclosure.

License for contributions

Hivenet Router is licensed under the Apache License 2.0. By contributing, you agree that your contribution will be licensed under the same terms. Read the complete License before submitting a contribution.

Contribution checklist

Before submitting:

the change has one clear purpose
new behavior has appropriate tests
existing tests pass
Go source is formatted
go vet ./... passes
the complete module builds
generated files were updated from their source
documentation reflects externally visible changes
secrets and sensitive data were removed
the pull request explains the reason and verification
the branch is based on a current main

Next steps

Canonical contribution guide

Read the authoritative repository version of the contribution instructions.

Code of conduct

Review the standards applying to project participation.

License

Review the Apache License 2.0 terms applying to contributions.

GitHub issues

Report bugs and discuss feature proposals.

Pull requests

Review current work or submit a focused change.

Detailed architecture

Understand the components and request paths affected by a code change.

Getting started

Deploy Hivenet Router

Use the API

Routing and policies

Security and auth

Observability

Integrations

Reference

Project

Report a bug

Propose a feature

Improve the documentation

Open a pull request

Development requirements

Repository structure

Run the tests

Add tests with a change

Format and check the code

Update dependencies carefully

Regenerate protobuf code

Improve the documentation

Report a bug

Propose a feature

Create a branch

Prepare the pull request

Review feedback

Report a security issue privately

License for contributions

Contribution checklist

Next steps

Canonical contribution guide

Code of conduct

License

GitHub issues

Pull requests

Detailed architecture

Report a bug

Propose a feature

Improve the documentation

Open a pull request

​Development requirements

​Repository structure

​Run the tests

​Add tests with a change

​Format and check the code

​Update dependencies carefully

​Regenerate protobuf code

​Improve the documentation

​Report a bug

​Propose a feature

​Create a branch

​Prepare the pull request

​Review feedback

​Report a security issue privately

​License for contributions

​Contribution checklist

​Next steps

Canonical contribution guide

Code of conduct

License

GitHub issues

Pull requests

Detailed architecture

Development requirements

Repository structure

Run the tests

Add tests with a change

Format and check the code

Update dependencies carefully

Regenerate protobuf code

Improve the documentation

Report a bug

Propose a feature

Create a branch

Prepare the pull request

Review feedback

Report a security issue privately

License for contributions

Contribution checklist

Next steps