Contributing Guide - Azure DevOps CLI

## 🚀 Welcome Contributors!

Thank you for your interest in contributing to azdocli! This document provides guidelines for contributing to the project. We welcome all contributions, from bug reports and feature requests to code improvements and documentation updates.

## 📜 Code of Conduct

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.

## ⚙️ Development Setup

### Prerequisites

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

#### Getting Started

    # 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

#### Setting up for Testing

    # 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)

## 🎨 Code Style and Patterns

### 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

## 🧪 Testing

### Test Types

#### Unit Tests

    # Run unit tests
    cargo test

Write unit tests for individual functions and modules where possible.

#### Integration Tests

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

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

Integration tests verify functionality against a real Azure DevOps instance.

#### 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

## 📝 Pull Request Guidelines

### 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

## ❓ Getting Help

### 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

#### Issue Templates

When creating issues, please provide:

- Clear description of the problem or feature request
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Environment details (OS, Rust version, etc.)
- Relevant error messages or logs

## 🚢 Release Process

### 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

## ✨ Best Practices

### 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