CONTRIBUTING.md

Contributing to rust-ai-driven-development-pipeline-template

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

Development Setup

1. Fork and clone the repository

   git clone https://github.com/YOUR-USERNAME/rust-ai-driven-development-pipeline-template.git
   cd rust-ai-driven-development-pipeline-template

2. Install Rust

   Install Rust using rustup (if not already installed):

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. Install development tools

   rustup component add rustfmt clippy

4. Install pre-commit hooks (optional but recommended)

   pip install pre-commit
   pre-commit install

5. Build the project

   cargo build

Development Workflow

1. Create a feature branch

   git checkout -b feature/my-feature

2. Make your changes

   • Write code following the project's style guidelines
   • Add tests for any new functionality
   • Update documentation as needed

3. Run quality checks

   # Format code
   cargo fmt
   
   # Run Clippy lints
   cargo clippy --all-targets --all-features
   
   # Check file sizes
   node scripts/check-file-size.mjs
   
   # Run all checks together
   cargo fmt --check && cargo clippy --all-targets --all-features && node scripts/check-file-size.mjs

4. Run tests

   # Run all tests
   cargo test
   
   # Run tests with verbose output
   cargo test --verbose
   
   # Run doc tests
   cargo test --doc
   
   # Run a specific test
   cargo test test_name

5. Add a changelog fragment

   For any user-facing changes, create a changelog fragment:

   # Create a new file in changelog.d/
   # Format: YYYYMMDD_HHMMSS_description.md
   touch changelog.d/$(date +%Y%m%d_%H%M%S)_my_change.md

   Edit the file to document your changes:

   ### Added
   - Description of new feature
   
   ### Fixed
   - Description of bug fix

   Why fragments? This prevents merge conflicts in CHANGELOG.md when multiple PRs are open simultaneously.

6. Commit your changes

   git add .
   git commit -m "feat: add new feature"

   Pre-commit hooks will automatically run and check your code.

7. Push and create a Pull Request

   git push origin feature/my-feature

   Then create a Pull Request on GitHub.

Code Style Guidelines

This project uses:

• rustfmt for code formatting
• Clippy for linting with pedantic and nursery lints enabled
• cargo test for testing

Code Standards

• Follow Rust idioms and best practices
• Use documentation comments (///) for all public APIs
• Write tests for all new functionality
• Keep functions focused and reasonably sized
• Keep files under 1000 lines
• Use meaningful variable and function names

Documentation Format

Use Rust documentation comments:

/// Brief description of the function.
///
/// Longer description if needed.
///
/// # Arguments
///
/// * `arg1` - Description of arg1
/// * `arg2` - Description of arg2
///
/// # Returns
///
/// Description of return value
///
/// # Errors
///
/// Description of when errors are returned
///
/// # Examples
///
/// ```
/// use my_package::example_function;
/// let result = example_function(1, 2);
/// assert_eq!(result, 3);
/// ```
pub fn example_function(arg1: i32, arg2: i32) -> i32 {
    arg1 + arg2
}

Testing Guidelines

• Write tests for all new features
• Maintain or improve test coverage
• Use descriptive test names
• Organize tests in modules when appropriate
• Use #[cfg(test)] for test-only code

Example test structure:

#[cfg(test)]
mod tests {
    use super::*;

    mod my_feature_tests {
        use super::*;

        #[test]
        fn test_basic_functionality() {
            assert_eq!(my_function(), expected_result);
        }

        #[test]
        fn test_edge_case() {
            assert_eq!(my_function(edge_case_input), expected_result);
        }
    }
}

Pull Request Process

1. Ensure all tests pass locally
2. Update documentation if needed
3. Add a changelog fragment (see step 5 in Development Workflow)
4. Ensure the PR description clearly describes the changes
5. Link any related issues in the PR description
6. Wait for CI checks to pass
7. Address any review feedback

Changelog Management

This project uses a fragment-based changelog system similar to Scriv (Python) and Changesets (JavaScript).

Creating a Fragment

# Create a new fragment with timestamp
touch changelog.d/$(date +%Y%m%d_%H%M%S)_description.md

Fragment Categories

Use these categories in your fragments:

• Added: New features
• Changed: Changes to existing functionality
• Deprecated: Features that will be removed in future
• Removed: Features that were removed
• Fixed: Bug fixes
• Security: Security-related changes

During Release

Fragments are automatically collected into CHANGELOG.md during the release process. The release workflow:

1. Collects all fragments
2. Updates CHANGELOG.md with the new version entry
3. Removes processed fragment files
4. Bumps the version in Cargo.toml
5. Creates a git tag and GitHub release

Project Structure

.
├── .github/workflows/    # GitHub Actions CI/CD
├── changelog.d/          # Changelog fragments
│   ├── README.md         # Fragment instructions
│   └── *.md              # Individual changelog fragments
├── examples/             # Usage examples
├── scripts/              # Utility scripts
├── src/
│   ├── lib.rs            # Library entry point
│   └── main.rs           # Binary entry point
├── tests/                # Integration tests
├── .gitignore            # Git ignore patterns
├── .pre-commit-config.yaml  # Pre-commit hooks
├── Cargo.toml            # Project configuration
├── CHANGELOG.md          # Project changelog
├── CONTRIBUTING.md       # This file
├── LICENSE               # Unlicense (public domain)
└── README.md             # Project README

Release Process

This project uses semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)

Releases are managed through GitHub releases. To trigger a release:

1. Manually trigger the release workflow with a version bump type
2. Or: Update the version in Cargo.toml and push to main

Getting Help

• Open an issue for bugs or feature requests
• Use discussions for questions and general help
• Check existing issues and PRs before creating new ones

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Focus on what is best for the community
• Show empathy towards other community members

Thank you for contributing!