Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
102 lines (72 loc) · 3.18 KB

CONTRIBUTING.md

File metadata and controls

102 lines (72 loc) · 3.18 KB

Contributing to Switchboard

Thank you for your interest in contributing! This guide will help you get started.

Development Model

This project uses a solo maintainer + AI agent team development model. The human maintainer (arcaven) directs a team of AI agents that handle most implementation work. All PRs are reviewed by the maintainer before merge.

You don't need to use AI agents to contribute -- just follow this guide and submit a PR like any other open-source project.

Prerequisites

  • Go 1.22+ -- install
  • just -- install
  • gofumpt -- go install mvdan.cc/gofumpt@latest
  • golangci-lint -- install

Getting Started

git clone https://github.com/ArcavenAE/switchboard.git
cd switchboard
just build    # Build
just test     # Run tests
just lint     # Run linter (golangci-lint)
just fmt      # Format code (gofumpt)

How to Contribute

Reporting Bugs

Open a Bug Report and include:

  • Version or commit hash
  • Operating system
  • Steps to reproduce
  • Expected vs actual behavior

Suggesting Features

Open a Feature Request.

This project is part of the Arcaven Agentic Engineering platform. Features should align with the project's design values: user sovereignty, composability over frameworks, and gradual elaboration.

Submitting Code

  1. Fork the repo and create a feature branch from develop: 
    git checkout -b feat/your-feature
  2. Write tests for your changes
  3. Run the full quality gate: 
    just fmt
just lint
just test
  4. Create a PR using the PR template

Commit Message Format

Conventional Commits:

type(scope): description

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

Examples:

  • feat: add session timeout configuration
  • fix: prevent crash on empty input
  • docs: update installation guide

Rules:

  • Imperative, present tense ("add feature" not "added feature")
  • No capitalized first letter in description
  • No period at end

Code Standards

  • Formatting: gofumpt (stricter than gofmt)
  • Linting: golangci-lint with zero warnings
  • Testing: Table-driven tests using stdlib testing (no testify)
  • Error handling: Always check errors, wrap with %w for context
  • No init() functions -- pass dependencies explicitly
  • Timestamps: Always time.Now().UTC()

See CLAUDE.md for the complete coding standards.

What NOT to Contribute

  • Heavy dependencies where the standard library suffices
  • Telemetry, analytics, or phone-home features
  • Features that create vendor lock-in or external service dependencies
  • Code that stores or manages credentials (auth is always delegated)
  • Testify or other test framework dependencies

License

This project is MIT licensed. By contributing, you agree that your contributions will be licensed under the same license.