Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
291 lines (202 loc) · 5.32 KB

CONTRIBUTING.md

File metadata and controls

291 lines (202 loc) · 5.32 KB

CONTRIBUTING.md

Contributing to TokenRouter

Thank you for your interest in contributing to TokenRouter! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

Please read and follow our Code of Conduct to maintain a welcoming and inclusive community.

Getting Started

1. Fork the Repository

Click the "Fork" button on GitHub and clone your fork:

git clone https://github.com/YOUR_USERNAME/TokenRouter.git
cd TokenRouter

2. Set Up Development Environment

# Install Go 1.21 or later
go version

# Install dependencies
go mod download

# Install development tools
make install-tools

3. Run Tests

# Run all tests
make test

# Run specific test package
go test ./internal/chunker -v

# Run with coverage
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out

Making Changes

1. Create a Branch

# Make sure you're on the main branch
git checkout dev

# Pull latest changes
git pull origin dev

# Create a feature branch
git checkout -b feature/your-feature-name

Branch naming conventions:

  • feature/ - New features
  • bugfix/ - Bug fixes
  • docs/ - Documentation changes
  • test/ - Test additions/updates
  • refactor/ - Code refactoring
  • perf/ - Performance improvements

2. Make Changes

Make your changes following our coding standards.

3. Commit Changes

# Stage changes
git add .

# Commit with conventional commit message
git commit -m "feat: add your feature description"

Commit message format:

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

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Refactoring
  • test: Tests
  • chore: Maintenance

Example:

feat(cache): add cache optimization for tool blocks

- Implement alphabetical sorting of tools
- Add configuration option to disable sorting
- Update documentation

Closes #123

Pull Request Guidelines

1. Before Submitting

  • Run all tests: make test
  • Run linters: make lint
  • Update documentation
  • Add tests for new functionality
  • Check for security issues
  • Review your own code first

2. Create Pull Request

# Push your branch
git push origin feature/your-feature-name

# Then open a PR on GitHub

3. PR Description Template

Use the provided PR template and fill in all sections.

4. Review Process

  1. Automated Checks: CI/CD will run tests and linters
  2. Code Review: Maintainers will review your code
  3. Address Feedback: Make requested changes
  4. Approval: Once approved, your PR will be merged

Coding Standards

Go Code Style

Code Organization

  • Keep functions small and focused
  • Use meaningful variable names
  • Add comments for complex logic
  • Avoid global variables

Error Handling

// Good
if err != nil {
    return fmt.Errorf("failed to process request: %w", err)
}

// Bad
if err != nil {
    log.Fatal(err) // Don't exit in library code
}

Logging

// Use structured logging
logger.Infof("Request processed: model=%s, tokens=%d", model, tokens)

// Avoid
fmt.Println("Request processed") // Don't use fmt.Println for logging

Testing

Test Coverage

Minimum coverage requirements:

  • Chunker: 80%
  • Arranger: 80%
  • Canonicalizer: 100% (critical for correctness)
  • Hasher: 80%
  • Outbound Adapters: 70%

Writing Tests

func TestMyFunction(t *testing.T) {
    // Arrange
    input := "test"
    expected := "result"
    
    // Act
    result := MyFunction(input)
    
    // Assert
    if result != expected {
        t.Errorf("expected %s, got %s", expected, result)
    }
}

Running Tests

# All tests
make test

# Specific package
go test ./internal/chunker -v

# With coverage
go test ./... -coverprofile=coverage.out

# View coverage
go tool cover -html=coverage.out

Documentation

Code Comments

  • Exported functions should have doc comments
  • Complex logic should be explained
  • Include examples when helpful

Documentation Updates

When adding features, update:

Documentation Style

  • Use clear, concise language
  • Include code examples
  • Add diagrams when helpful
  • Keep documentation in sync with code

Questions?

If you have questions, please:

  1. Check existing issues
  2. Start a discussion
  3. Ask in the PR description

Thank You!

Your contributions make TokenRouter better for everyone. We appreciate your time and effort!