Contributing

Thank you for your interest in contributing to AxonFlow!

Ways to Contribute

Contribution	Description
Bug Reports	Report issues on GitHub
Feature Requests	Suggest new features
Documentation	Improve docs and examples
Code	Submit pull requests
Testing	Help test new releases

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

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

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

Pull Request Process

1. Create PR with clear title following Conventional Commits

   • feat(agent): add new policy type
   • fix(orchestrator): resolve timeout issue
   • docs(sdk): update Python examples

2. Fill out PR template with description, testing steps, and screenshots if applicable

3. Ensure CI passes - all tests and linting must pass

4. Request review from maintainers

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

  import (
      "context"
      "fmt"
      "net/http"
  
      "github.com/gorilla/mux"
      "go.uber.org/zap"
  
      "axonflow/platform/orchestrator/llm"
      "axonflow/platform/shared/policy"
  )

• Naming: Use MixedCaps or mixedCaps (no underscores in Go names). Acronyms are all-caps: HTTPClient, SQLDB.

• Error handling: Always handle errors explicitly. Do not use _ to discard errors.

• Comments: All exported functions, types, and constants must have doc comments starting with the name.

Linting

The project uses golangci-lint with a configuration in .golangci.yml. Run it locally before submitting a PR:

# Install golangci-lint (if not already installed)
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

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

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

CI runs golangci-lint on every PR. The following linters are enabled: govet, errcheck, staticcheck, unused, gosimple, ineffassign, and typecheck.

Additionally, the project includes a custom lint script for deployment mode checks:

# Verify isCommunityMode() usage pattern
./scripts/lint-deployment-mode.sh

Commit Messages

Follow Conventional Commits:

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

[optional body]

[optional footer]

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

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