Contributing Guide¶

This guide walks you through the complete process of contributing to AutoDocs MCP Server, from initial setup to getting your changes merged.

Quick Start¶

1. Set Up Your Development Environment¶

Clone and Install:

# Clone the repository
git clone https://github.com/bradleyfay/autodocs.git
cd autodocs

# Install with development dependencies
uv sync

# Verify installation
uv run python -m autodoc_mcp.main --help

Verify Your Setup:

# Run the test suite
uv run python -m pytest

# Check code quality
uv run pre-commit run --all-files

# Test MCP server startup
echo '{}' | uv run python -m autodoc_mcp.main

2. Understand the Codebase¶

Before making changes, familiarize yourself with: - System Architecture - Understanding component organization - Development Standards - Code conventions and requirements - Testing Guide - How to write and run tests

Development Workflow¶

Step 1: Branch Management¶

Check Current Branch:

git status
git branch

Create Feature Branch:

# Always branch from develop for new features
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-description

# For bug fixes, you can branch from main if critical
git checkout main
git pull origin main
git checkout -b fix/bug-description

Step 2: Make Your Changes¶

Follow Development Standards: - Write tests for new functionality (see Testing Guide) - Follow code quality standards - Use conventional commit messages - Document technical debt if making compromises

Test Your Changes:

# Run tests frequently during development
uv run python -m pytest tests/unit/

# Run specific tests for your changes
uv run python -m pytest tests/unit/test_your_module.py -v

# Check code quality
uv run pre-commit run --all-files

Step 3: Commit Your Changes¶

Stage and Commit:

# Review your changes
git diff

# Stage changes
git add .

# Commit with conventional message
git commit -m "feat: add smart dependency context filtering

- Implement token-aware context selection
- Add runtime vs dev dependency classification
- Include configurable context scoping options

Closes #123"

Pre-commit Hook Compliance: - Pre-commit hooks run automatically on every commit - If hooks fail, fix the issues and commit again - NEVER use --no-verify to bypass hooks

Step 4: Push and Create Pull Request¶

Push Your Branch:

git push -u origin feature/your-feature-description

Create Pull Request: 1. Navigate to the GitHub repository 2. Click "Compare & pull request" for your branch 3. Fill out the PR template with: - Clear description of changes - Testing performed - Related issues - Breaking changes (if any)

Types of Contributions¶

Bug Fixes¶

Process for Bug Fixes: 1. Reproduce the Issue: Create a failing test that demonstrates the bug 2. Fix the Code: Implement the minimal fix needed 3. Verify the Fix: Ensure the test passes and no regressions 4. Update Documentation: If the bug was in documented behavior

Example Bug Fix Workflow:

# Create bug fix branch
git checkout -b fix/cache-corruption-on-concurrent-access

# Write failing test
# Edit tests/unit/test_cache_manager.py

# Run test to confirm failure
uv run python -m pytest tests/unit/test_cache_manager.py::test_concurrent_access -v

# Implement fix
# Edit src/autodoc_mcp/core/cache_manager.py

# Verify fix
uv run python -m pytest tests/unit/test_cache_manager.py::test_concurrent_access -v

# Commit fix
git commit -m "fix: resolve cache corruption on concurrent access

- Add file locking for cache write operations
- Implement retry logic for lock contention
- Add test coverage for concurrent cache access

Fixes #456"

New Features¶

Process for New Features: 1. Design First: Consider architectural impact and create issue for discussion 2. Test-Driven Development: Write tests before implementation 3. Incremental Implementation: Break large features into smaller commits 4. Documentation: Update relevant documentation

Example Feature Implementation:

# Create feature branch
git checkout -b feature/add-semantic-search-filtering

# Write tests first (TDD)
# Edit tests/unit/test_context_formatter.py

# Implement feature incrementally
# Edit src/autodoc_mcp/core/context_formatter.py

# Test continuously
uv run python -m pytest tests/unit/test_context_formatter.py -v

# Update integration tests
# Edit tests/integration/test_mcp_server.py

# Update documentation
# Edit docs/product/mcp-tools.md

# Commit with conventional message
git commit -m "feat: add semantic search filtering for documentation

- Implement query-based section filtering
- Add relevance scoring for documentation sections
- Include configurable similarity threshold
- Update MCP tool to accept search queries

Closes #789"

Documentation Improvements¶

Types of Documentation: - Code Documentation: Docstrings, inline comments - User Documentation: Setup guides, tutorials, how-to guides - Developer Documentation: Architecture, contributing guides

Documentation Standards: - Follow Diátaxis framework for user documentation - Use clear, concise language appropriate for the audience - Include code examples and practical guidance - Test all code examples to ensure they work

Code Review Process¶

Submitting for Review¶

Before Requesting Review: - [ ] All tests pass locally - [ ] Code meets quality standards (Ruff, MyPy clean) - [ ] Documentation updated if needed - [ ] Conventional commit messages used - [ ] PR description is complete

PR Description Template:

## Summary
Brief description of the changes and why they're needed.

## Changes Made
- Bullet point list of specific changes
- Focus on what changed, not how it was implemented

## Testing Performed
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing performed

## Related Issues
Closes #123
Related to #456

## Breaking Changes
None / Describe any breaking changes

## Additional Notes
Any additional context, deployment notes, or follow-up work needed.

Review Criteria¶

Technical Requirements: - [ ] Code follows established patterns and architecture - [ ] Tests provide adequate coverage - [ ] Error handling is comprehensive - [ ] Performance impact is acceptable - [ ] Security considerations addressed

Quality Standards: - [ ] Code is readable and well-documented - [ ] Commit messages follow conventional commits - [ ] No pre-commit hook violations - [ ] Technical debt is documented if introduced

Addressing Review Feedback¶

Responding to Feedback: 1. Address All Comments: Respond to each review comment 2. Make Requested Changes: Implement suggested improvements 3. Explain Decisions: If you disagree, explain your reasoning 4. Request Re-review: After addressing feedback, request another review

Making Review Changes:

# Make requested changes
# Edit relevant files

# Test changes
uv run python -m pytest

# Commit additional changes
git commit -m "refactor: address review feedback

- Extract complex method into smaller functions
- Add missing error handling for edge cases
- Improve variable naming for clarity"

# Push updates
git push origin feature/your-feature-description

Advanced Contributing Scenarios¶

Working with Existing Issues¶

Finding Issues to Work On: - Look for issues labeled good-first-issue for beginners - Check issues labeled help-wanted for intermediate contributors - Review the project roadmap for strategic contributions

Claiming an Issue: 1. Comment on the issue expressing interest 2. Ask questions about requirements or approach 3. Wait for maintainer acknowledgment before starting work

Contributing to Architecture¶

Major Architectural Changes: 1. Create RFC: For significant changes, create a Request for Comments 2. Discuss First: Use GitHub Discussions for architectural conversations 3. Prototype: Create proof-of-concept implementations 4. Incremental Migration: Break changes into manageable steps

Performance Improvements¶

Performance Contribution Process: 1. Measure First: Establish baseline performance metrics 2. Identify Bottlenecks: Use profiling tools to find actual issues 3. Implement Optimization: Make targeted improvements 4. Verify Improvement: Measure performance impact 5. Add Benchmarks: Include performance tests to prevent regressions

Troubleshooting Common Issues¶

Development Environment Issues¶

uv Installation Problems:

# Reinstall uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clear uv cache
uv cache clean

# Reinstall dependencies
rm -rf .venv
uv sync

Test Failures:

# Run tests with verbose output
uv run python -m pytest -v -s

# Run specific failing test
uv run python -m pytest tests/unit/test_specific.py::test_method -v -s

# Check test isolation
uv run python -m pytest --lf --tb=short

Pre-commit Hook Issues:

# Install pre-commit hooks
uv run pre-commit install

# Run hooks manually
uv run pre-commit run --all-files

# Skip specific hooks if needed (debugging only)
SKIP=mypy git commit -m "debug: temporary commit to test changes"

Git Workflow Issues¶

Branch Management:

# Switch to develop branch
git checkout develop

# Update develop branch
git pull origin develop

# Rebase feature branch on latest develop
git checkout feature/your-feature
git rebase develop

# Resolve conflicts if needed
git add .
git rebase --continue

Commit Message Issues:

# Fix the last commit message
git commit --amend -m "feat: correct conventional commit message"

# Interactive rebase to fix multiple commits
git rebase -i HEAD~3

Getting Help¶

Resources for Contributors¶

Architecture Questions: Review System Architecture
Code Standards: Check Development Standards
Testing Help: See Testing Guide
Technical Decisions: Read Technical Decisions

Communication Channels¶

GitHub Issues: For bug reports and feature requests
GitHub Discussions: For architectural discussions and questions
Pull Request Comments: For code-specific discussions
Code Documentation: Inline comments and docstrings for implementation details

Contribution Recognition¶

Contributors are recognized through: - GitHub contributor statistics - Release notes acknowledgments - Code author attribution in git history - Community recognition for significant contributions

Thank you for contributing to AutoDocs MCP Server! Your contributions help improve AI-assisted development for the entire Python community.