Contributing

Thank you for your interest in contributing to AxonFlow. Contributions here affect a runtime that engineers use for governed LLM traffic, MCP tool access, workflow orchestration, and audit-heavy production systems, so the bar is intentionally high on accuracy, testing, and operational clarity.

Ways to Contribute

Contribution	Description
Bug Reports	Report issues on GitHub
Feature Requests	Suggest new features
Documentation	Improve docs, examples, and reference guides
Code	Submit pull requests
Testing	Help strengthen unit, integration, and performance coverage

Getting Started

1. Fork and Clone

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/axonflow.git
cd axonflow

2. Set Up Development Environment

# Start local environment
docker compose up -d

# Verify health
curl -sf http://localhost:8080/health | jq .
curl -sf http://localhost:8081/health | jq .

# Run tests to verify setup
go test ./platform/...

Before opening a PR, make sure you can do all three of these locally:

• bring up the runtime with docker compose up -d
• verify Agent and Orchestrator health
• run the relevant unit or integration tests for the area you changed

3. Create a Branch

git checkout -b feat/your-feature-name
# or
git checkout -b fix/your-bug-fix

Contribution Guides

Guide	Description
Writing Tests	Test conventions and patterns
Development Overview	Local runtime and contributor setup

Release Notes Policy

The Release Notes section is curated, not generated from CHANGELOG entries. The policy is simple:

• Every MINOR platform release gets a dedicated page. These are the releases where callers, SDK users, or operators have to do something different than before, so the narrative-style page is warranted.
• PATCH releases get a page when they change user-visible behavior. Fixes that matter to people running AxonFlow in production (a handler that used to 500, a portal page that used to crash, a new surface a caller can now consume) belong on a release page. Fixes that are purely internal (CI, test coverage, refactors, lint cleanups) do not.
• SDK and plugin releases are covered inside the platform release page they ship alongside. Standalone SDK release notes are not maintained as separate docs pages — the CHANGELOG in each SDK repo is the authoritative source for per-SDK change history.

When you open a PR that warrants a release notes page, add the file at docs/releases/v<major>-<minor>-<patch>.md and wire it into sidebars.ts under the Release Notes category. Follow the shape of the most recent existing page — narrative grouped by audience impact (Community / Evaluation / Enterprise, or SDK users / operators / plugin users), heavy internal cross-linking, and an upgrade checklist. Not a CHANGELOG dump.

Pull Request Process

1. Create PR with a clear title following Conventional Commits
   • feat(agent): add new policy type
   • fix(orchestrator): resolve timeout issue
   • docs(sdk): update Python examples
2. Fill out the PR template with description, testing steps, and screenshots if applicable
3. Ensure CI passes before asking for merge
4. Request review from maintainers

For docs, API, and SDK changes, “looks plausible” is not enough. Reviewers will often validate examples and endpoints directly against the source because these docs are used by senior engineers making architecture decisions.

Code Style

Go Formatting Conventions

All Go code must follow these conventions:

• Formatting: Run gofmt on all files. CI will reject unformatted code.
• Import ordering: Group imports into three blocks separated by blank lines:
  1. Standard library imports
  2. Third-party imports
  3. Internal project imports
• Naming: Use MixedCaps or mixedCaps in Go names. Acronyms remain all caps: HTTPClient, SQLDB.
• Error handling: Always handle errors explicitly.
• Comments: All exported functions, types, and constants should have doc comments that begin with the symbol name.

Linting

The project uses golangci-lint and other CI checks. Run them locally before submitting a PR:

# Install golangci-lint if needed
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run linter
golangci-lint run ./platform/...

# Optional auto-fix for simple issues
golangci-lint run --fix ./platform/...

# Verify deployment-mode usage patterns
./scripts/lint-deployment-mode.sh

If you touch request handling, policies, connectors, or workflow behavior, it is a good idea to run the smallest targeted test scope that proves the change rather than relying only on the broadest suite.

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Common types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

High-Value Areas to Help

The most useful contributions usually fall into one of these areas:

• SDK and example accuracy fixes
• policy and connector documentation improvements
• workflow and orchestration reliability issues
• deployment and monitoring runbook improvements
• new examples that show realistic governed AI workloads rather than toy prompts

Community

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and ideas
• Discord: Real-time chat (coming soon)

License

By contributing, you agree that your contributions will be licensed under the BSL 1.1 license.

Next Steps

• Read Writing Tests for test conventions
• Check open issues labeled good first issue
• Review the Development Guide