Contributing to Forge

​

Ways to Contribute

• 🐛 Report bugs - Help us identify and fix issues
• 💡 Suggest features - Share ideas for new capabilities
• 📝 Improve documentation - Make our docs clearer and more comprehensive
• 🔧 Submit code - Fix bugs or implement new features
• 🧪 Write tests - Improve test coverage and reliability
• 🎨 Enhance UI/UX - Improve the terminal interface and user experience
• 🌍 Help others - Answer questions on Discord and GitHub
• ⭐ Spread the word - Star the repository and share with others

​

Getting Started

​

Prerequisites

• Rust toolchain (1.75+) - Install from rustup.rs
• Git - For version control
• GitHub account - For submitting contributions
• Node.js (16+) - For npm-related tasks
• Optional: GitHub CLI (gh) for PR operations

​

Setting Up Development Environment

1. Fork the repository Visit github.com/antinomyhq/forge and click “Fork”
2. Clone your fork
   git clone https://github.com/YOUR_USERNAME/forge.git
   cd forge
   
3. Add upstream remote
   git remote add upstream https://github.com/antinomyhq/forge.git
   
4. Install dependencies
   cargo build
   
5. Verify setup
   cargo check
   cargo test
   

​

Development Guidelines

​

Code Style

• Formatting: Use rustfmt for code formatting
  cargo fmt
  
• Linting: Run clippy before submitting
  cargo clippy --all-targets --all-features
  
• Documentation: Write Rust docs (///) for all public APIs
  • Document parameters with # Arguments
  • Document errors with # Errors
  • Focus on clear functionality descriptions
  • Avoid code examples (docs are for LLMs)

​

Error Handling

• Use anyhow::Result for error handling in services and repositories
• Create domain errors using thiserror
• Never implement From for converting domain errors; convert them manually

​

Writing Tests

use pretty_assertions::assert_eq;

#[test]
fn test_user_creation() {
    // 1. Setup - Create fixtures
    let fixture = UserFixture::default()
        .with_name("Alice")
        .with_age(30);
    
    // 2. Execute - Run the code under test
    let actual = create_user(fixture);
    
    // 3. Assert - Compare with expected result
    let expected = User::new("Alice").age(30);
    assert_eq!(actual, expected);
}

• Use pretty_assertions for better error messages
• Use fixtures to create test data
• Keep tests in the same file as source code
• Use Default, new(), and derive_setters::Setters for test objects
• Prefer unwrap() in tests; use expect() when error context is useful
• Assert on full objects rather than individual fields

​

Running Tests

# Run all tests
cargo test

# Run tests with snapshot testing
cargo insta test --accept

# Run specific crate tests
cargo test -p forge_main

​

Building

# Fast validation (recommended)
cargo check

# Debug build
cargo build

# Release build (only when necessary)
cargo build --release

​

Project Structure

forge/
├── crates/
│   ├── forge_main/        # CLI and main application
│   ├── forge_domain/      # Core domain models
│   ├── forge_services/    # Business services
│   ├── forge_tool/        # Tool implementations
│   └── forge_walker/      # File system operations
├── docs/                  # Documentation
├── shell-plugin/          # ZSH integration
└── templates/             # Project templates

​

Service Implementation Guidelines

• No service-to-service dependencies
• Services depend only on infrastructure abstractions
• Single type parameter for infrastructure
• No trait objects (Box<dyn ...>)
• Constructor pattern without type bounds
• Use Arc<T> for infrastructure
• Tuple struct pattern for simple services

// Simple service without infrastructure
pub struct ValidationService;

impl ValidationService {
    pub fn new() -> Self { Self }
    
    pub fn validate_email(&self, email: &str) -> Result<()> {
        // Implementation
    }
}

// Service with infrastructure dependency
pub struct UserService<R> {
    repository: Arc<R>,
}

impl<R> UserService<R> {
    pub fn new(repository: Arc<R>) -> Self {
        Self { repository }
    }
}

impl<R: UserRepository> UserService<R> {
    pub fn create_user(&self, email: &str) -> Result<User> {
        // Implementation
    }
}

​

Making Changes

​

Creating a Branch

# Update your fork
git checkout main
git pull upstream main

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

​

Commit Guidelines

• Write clear, descriptive commit messages
• Use conventional commit format:
  feat: add new semantic search feature
  fix: resolve provider authentication issue
  docs: update installation guide
  test: add tests for conversation service
  refactor: simplify error handling logic
  
• Include co-author attribution:
  git commit -m "feat: add feature" -m "Co-Authored-By: ForgeCode <[email protected]>"
  

​

Submitting Pull Requests

1. Push your changes
   git push origin feature/your-feature-name
   
2. Create a pull request
   • Visit your fork on GitHub
   • Click “New Pull Request”
   • Select your feature branch
   • Fill out the PR template
3. PR checklist
   • Tests pass (cargo test)
   • Code is formatted (cargo fmt)
   • No clippy warnings (cargo clippy)
   • Documentation is updated
   • Commit messages follow conventions
   • PR description explains changes clearly
   • Co-author attribution included
4. Sign the CLA First-time contributors must sign the Contributor License Agreement. The CLA assistant bot will guide you through this process.

​

Code Review Process

• Maintainers will review your PR
• Address feedback by pushing new commits
• Once approved, your PR will be merged
• Squash commits may be used for cleaner history

​

Reporting Issues

​

Bug Reports

• Clear description of the bug
• Steps to reproduce the issue
• Expected behavior vs actual behavior
• Error logs (run with --verbose)
• Forge version (forge --version)
• Operating system and version
• AI provider and model
• Configuration (forge.yaml, with secrets removed)

​

Feature Requests

• Use case - What problem does this solve?
• Proposed solution - How should it work?
• Alternatives - What other solutions have you considered?
• Additional context - Screenshots, examples, references

​

Other Issue Types

• Documentation improvements
• Performance issues
• Provider integration requests

​

Documentation Contributions

​

Setting Up Documentation Environment

cd docs
npm install -g mint
mint dev

​

Documentation Guidelines

• Use active voice: “Run the command” not “The command should be run”
• Address the reader directly: Use “you” instead of “the user”
• Keep sentences concise: One idea per sentence
• Lead with the goal: Start with what the user wants to accomplish
• Use consistent terminology: Don’t alternate between synonyms
• Include examples: Show, don’t just tell
• Use sentence case for headings
• Bold UI elements: Click Settings
• Code formatting: For file names, commands, paths

​

Community Guidelines

​

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers and help them learn
• Accept constructive criticism gracefully
• Focus on what’s best for the community
• Show empathy towards other community members

​

Getting Help

• Discord: discord.gg/kRZBPpkgwq - Chat with the community
• GitHub Discussions: Ask questions and share ideas
• GitHub Issues: Report bugs and request features

​

Recognition

• GitHub contributor graph
• Release notes acknowledgments
• Community shoutouts on Discord

​

Release Process

1. Version is bumped following Semantic Versioning
2. Changelog is updated with release notes
3. Release is tagged and published to GitHub
4. NPM package is updated
5. Documentation is updated

​

Git Operations

• Git and GitHub CLI (gh) are pre-installed in the development environment
• Always use Co-Authored-By: ForgeCode <[email protected]> for commits
• Use GitHub CLI for PR operations when possible

​

Additional Resources

• Source Code: github.com/antinomyhq/forge
• Documentation: forgecode.dev/docs
• Discord: discord.gg/kRZBPpkgwq
• Issue Templates: GitHub Issues
• Agent Guidelines: See AGENTS.md in the repository

​

Questions?

1. Check this guide and the FAQ
2. Search existing issues
3. Ask on Discord
4. Create a GitHub Discussion