🤝 Contributing Guide

By participating in this project, you agree to maintain a respectful and inclusive environment. We are committed to providing a welcoming and harassment-free experience for everyone.

Prerequisites

• Rust 1.70+ (latest stable recommended)
• Git
• Azure DevOps account with PAT for testing

# Clone the repository
git clone https://github.com/christianhelle/azdocli.git
cd azdocli

# Build the project
cargo build

# Run tests
cargo test

# Run the CLI
cargo run -- --help

# Copy test configuration template
cp test_config.json.template test_config.json

# Edit test_config.json with your Azure DevOps credentials
# (This file is git-ignored for security)

Follow Existing Patterns

This project follows standard Rust conventions and established patterns. Please ensure your code is consistent with the existing codebase.

Project Structure

• Modular design: Each Azure DevOps service area has its own module (auth.rs, boards.rs, pipelines.rs, repos.rs)
• Command handling: Each module has a handle_command() function that takes subcommands and delegates to specific functions
• Consistent imports: Group imports by: standard library, external crates, internal modules

Code Conventions

• Use descriptive variable and function names
• Follow Rust naming conventions (snake_case for functions/variables, PascalCase for types)
• Keep functions focused and single-purpose
• Use proper error handling with anyhow::Result
• Include comprehensive docstring comments for public functions

Code Quality

Formatting and Linting

# Format code before committing
cargo fmt

# Run clippy and fix all warnings
cargo clippy

# Both are required - CI will reject PRs that don't pass these checks

Documentation

• Add docstring comments (///) for public functions, especially CLI commands
• Keep inline comments minimal but use them to explain complex logic
• Update README.md if your changes affect usage or add new features

Test Types

# Run unit tests
cargo test

# Run integration tests (requires test_config.json)
cargo test -- --ignored

# Run specific integration test
cargo test test_create_show_clone_delete_repository -- --ignored

Test Guidelines

• Write tests for new functionality
• Ensure tests are isolated and don't depend on external state
• Use descriptive test names that explain what is being tested
• Integration tests should clean up after themselves
• Use a dedicated test project/organization for integration tests

Before Submitting

1. Test thoroughly: Ensure your changes work and don't break existing functionality
2. Update documentation: Keep README.md current with any new features or changes
3. Check CI requirements: Ensure your code passes formatting and linting
4. Create focused commits: Make commits atomic and with clear messages
5. Rebase if needed: Keep a clean commit history

PR Description Requirements

Use this template for your PR description:

## Description
Brief description of what this PR does

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Manually tested CLI commands: `cargo run -- <commands>`
- [ ] Tested on [Windows/Linux/macOS]

## Breaking Changes
List any breaking changes or "None"

## Documentation Updates
- [ ] Updated README.md
- [ ] Updated inline documentation
- [ ] Updated CONTRIBUTING.md (if process changes)

Fixes #<issue-number>

README Maintenance

When to update README.md:

• Adding new commands or features
• Changing existing command behavior
• Adding new installation methods
• Updating usage examples
• Adding new dependencies that affect users

README sections to maintain:

• Features: Update feature list for new capabilities
• Usage: Add examples for new commands
• Building from Source: Update if build process changes
• Examples: Ensure all examples work with current code

Support Channels

• Issues: Create an issue for bugs or feature requests
• Discussions: Use discussions for questions about contributing
• Code Patterns: Reference existing code patterns when in doubt
• PR Questions: Ask questions in your PR if you're unsure about implementation details

For Contributors

Maintainers handle releases. Contributors should:

• Ensure changes are backward compatible when possible
• Document breaking changes clearly
• Update version numbers only if instructed
• Follow semantic versioning principles

For Maintainers

• Review all PRs thoroughly
• Ensure CI passes before merging
• Update CHANGELOG.md for releases
• Tag releases following semantic versioning
• Publish to crates.io and GitHub releases

Development Workflow

1. Fork and Clone: Fork the repository and clone your fork
2. Create Feature Branch: Create a branch for your feature/fix
3. Make Changes: Implement your changes following the guidelines
4. Test Locally: Run tests and manual testing
5. Commit Changes: Make atomic commits with clear messages
6. Push and PR: Push to your fork and create a pull request
7. Address Feedback: Respond to review comments promptly

Commit Message Guidelines

# Good commit messages
feat: add parallel repository cloning support
fix: handle authentication errors gracefully
docs: update README with new installation methods
test: add integration tests for pipeline commands

# Use conventional commit format when possible
# type(scope): description

Code Review Checklist

• Code follows project conventions and style
• Tests are included and passing
• Documentation is updated if needed
• No breaking changes without proper discussion
• Error handling is appropriate
• Performance considerations are addressed