Contributing to AIRS Protocols¶

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

Ways to Contribute¶

There are many ways to contribute to AIRS Protocols:

🐛 Report Bugs: Find and report issues
💡 Suggest Features: Propose new capabilities
📝 Improve Documentation: Fix typos, clarify instructions, add examples
🔧 Write Code: Fix bugs, implement features, optimize performance
🧪 Write Tests: Add test coverage, create integration tests
💬 Help Others: Answer questions in discussions

Getting Started¶

Prerequisites¶

Rust 1.88 or later
Git for version control
Cargo (comes with Rust)
A GitHub account

Development Setup¶

Fork the Repository

Visit github.com/airsstack/airsprotocols and click "Fork"

Clone Your Fork

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

Add Upstream Remote

git remote add upstream https://github.com/airsstack/airsprotocols.git

Install Development Tools

# Install rustfmt for code formatting
rustup component add rustfmt

# Install clippy for linting
rustup component add clippy

# Install mdBook for documentation (optional)
cargo install mdbook

Build the Project

cargo build

Run Tests

cargo test --workspace

Development Workflow¶

1. Create a Branch¶

Create a branch for your changes:

git checkout -b feature/your-feature-name

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring
test/ - Test additions or modifications

2. Make Changes¶

Follow our coding standards (see below) and make your changes.

3. Test Your Changes¶

# Run all tests
cargo test --workspace

# Run specific package tests
cargo test -p airsprotocols-mcp

# Run with output
cargo test -- --nocapture

# Run integration tests
cargo test --test '*' -- --test-threads=1

4. Format and Lint¶

# Format code
cargo fmt --all

# Run clippy
cargo clippy --workspace --all-targets -- -D warnings

5. Commit Your Changes¶

Follow conventional commit message format:

type(scope): short description

Longer description if needed.

Fixes #issue_number

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - refactor: Code refactoring - test: Test additions/modifications - chore: Maintenance tasks

Example:

git add .
git commit -m "feat(mcp): add OAuth2 token refresh support

Implements automatic token refresh for OAuth2 authentication
to improve user experience and reduce authentication failures.

Fixes #123"

6. Push and Create Pull Request¶

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Coding Standards¶

Rust Code Style¶

Follow these guidelines:

Use rustfmt: All code must be formatted with cargo fmt
Follow Clippy: Address all clippy warnings with cargo clippy
Document Public APIs: All public items must have documentation comments

/// Describes what this function does.
///
/// # Arguments
///
/// * `param` - Description of parameter
///
/// # Returns
///
/// Description of return value
///
/// # Errors
///
/// Description of error conditions
pub fn my_function(param: Type) -> Result<ReturnType, Error> {
    // implementation
}

Use Explicit Error Handling: Avoid unwrap() and expect() in library code

// Bad
let value = some_result.unwrap();

// Good
let value = some_result?;
// or
let value = some_result.map_err(|e| MyError::from(e))?;

Follow Workspace Lint Rules: The workspace defines mandatory lints

// These are denied in production code:
// - unwrap_used
// - expect_used
// - panic

Testing Standards¶

Write Tests for New Code: All new features should include tests
Test Public APIs: Focus on testing the public interface
Use Descriptive Test Names:

#[test]
fn test_tool_provider_returns_correct_result() {
    // test implementation
}

Include Integration Tests: For cross-component functionality
Use Property-Based Testing: For complex algorithms (using proptest)

Documentation Standards¶

Clear and Concise: Write for your audience
Include Examples: Show how to use the API

/// # Example
///
/// ```rust
/// let client = McpClientBuilder::new()
///     .build(transport)
///     .await?;
/// ```

Update Related Docs: Keep documentation synchronized with code
Follow Diataxis Framework: Use the documentation guidelines in .aiassisted/guidelines/documentation/

Pull Request Process¶

Before Submitting¶

Code is formatted (cargo fmt)
All tests pass (cargo test)
No clippy warnings (cargo clippy)
Documentation is updated
Commit messages follow conventions
Branch is up to date with main

PR Description¶

Include in your PR description:

What: What does this PR do?
Why: Why is this change needed?
How: How does it work?
Testing: How was it tested?
Issues: References to related issues

Example:

## What

Adds OAuth2 token refresh support to the MCP HTTP client.

## Why

Users were experiencing authentication failures when tokens expired,
requiring manual re-authentication.

## How

Implements automatic token refresh using the refresh token. The client
now monitors token expiration and proactively refreshes before expiry.

## Testing

- Added unit tests for token refresh logic
- Added integration test with mock OAuth2 server
- Tested with Claude Desktop integration

## Issues

Fixes #123
Related to #456

Review Process¶

Automated Checks: CI runs tests and linting
Code Review: Maintainers review your code
Address Feedback: Make requested changes
Approval: PR is approved
Merge: Maintainers merge your PR

Code Review Guidelines¶

For Contributors¶

Be Receptive: Accept feedback gracefully
Ask Questions: If feedback is unclear, ask for clarification
Make Changes: Address review comments promptly
Learn: Use reviews as learning opportunities

For Reviewers¶

Be Respectful: Provide constructive feedback
Be Specific: Explain why changes are needed
Praise Good Work: Acknowledge good solutions
Focus on Code: Review the code, not the person

Development Guidelines¶

Architecture¶

Follow the established architecture patterns:

Integration Layer: High-level APIs
Provider Layer: Capability implementations
Protocol Layer: Message types and validation
Transport Layer: Communication abstractions

See Architecture Guide for details.

Error Handling¶

Use Result types and custom error types:

#[derive(Debug, thiserror::Error)]
pub enum MyError {
    #[error("connection failed: {0}")]
    ConnectionFailed(String),

    #[error("protocol error: {0}")]
    ProtocolError(String),
}

Async Code¶

All I/O should be async:

#[async_trait]
pub trait MyTrait: Send + Sync {
    async fn my_method(&self) -> Result<T, Error>;
}

Community Guidelines¶

Code of Conduct¶

Be respectful, inclusive, and professional:

Be Welcoming: Welcome newcomers
Be Respectful: Respect differing viewpoints
Be Constructive: Provide constructive criticism
Be Patient: Help others learn

Getting Help¶

Documentation: Check the docs first
Discussions: Ask in GitHub Discussions
Issues: Report bugs in GitHub Issues

Project Structure¶

airsprotocols/
├── protocols/          # Protocol implementations
│   ├── mcp/           # Model Context Protocol
│   └── a2a/           # Agent-to-Agent (planned)
├── apis/              # LLM APIs (planned)
├── docs/              # Documentation source
├── site-mkdocs/       # MkDocs configuration
└── .aiassisted/       # Development guidelines

Release Process¶

Maintainers handle releases, but here's the process:

Version Bump: Update version in Cargo.toml
Changelog: Update CHANGELOG.md
Tag: Create git tag
Publish: Publish to crates.io
Announce: Announce release

Recognition¶

Contributors are recognized in:

Repository contributor list
Release notes
Documentation acknowledgments

Questions?¶

If you have questions about contributing:

Check this guide
Ask in GitHub Discussions
Review existing PRs for examples
Contact maintainers

Thank you for contributing to AIRS Protocols! 🦀