Skip to content

Contributing to codebrief

Thank you for your interest in contributing to codebrief! We welcome contributions from developers of all skill levels. This guide will help you get started with contributing to our project.

📋 Table of Contents

📜 Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

🚀 Getting Started

Prerequisites

  • Python 3.9+: codebrief requires Python 3.9 or higher
  • Poetry: For dependency management and virtual environments
  • Git: For version control
  • Pre-commit: For automated code quality checks

Development Setup

  1. Fork and Clone the Repository

    # Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/codebrief.git
cd codebrief

  2. Install Dependencies

    # Install all dependencies including development tools
poetry install --with dev

  3. Set Up Pre-commit Hooks

    # Install pre-commit hooks for automated quality checks
poetry run pre-commit install

  4. Verify Installation

    # Run tests to ensure everything is working
poetry run pytest

# Run the CLI to verify installation
poetry run codebrief --help

🤝 How to Contribute

Types of Contributions

We welcome several types of contributions:

  • 🐛 Bug Reports: Help us identify and fix issues
  • ✨ Feature Requests: Suggest new functionality
  • 📝 Documentation: Improve or add documentation
  • 🧪 Tests: Add or improve test coverage
  • 🔧 Code: Fix bugs or implement new features
  • 🎨 UI/UX: Improve the CLI interface and user experience

🐛 Reporting Bugs

Before creating a bug report, please check the existing issues to avoid duplicates.

Bug Report Template

When reporting bugs, please use our issue template and include:

  • Clear Description: What happened vs. what you expected
  • Reproduction Steps: Detailed steps to reproduce the issue
  • Environment: OS, Python version, codebrief version
  • Error Messages: Full error messages and stack traces
  • Sample Files: Minimal example files if relevant

Example:

**Bug Description**
The `codebrief tree` command crashes when encountering symlinks.

**Steps to Reproduce**
1. Create a symlink: `ln -s /path/to/target symlink`
2. Run: `codebrief tree`
3. Observe the error

**Expected Behavior**
The command should handle symlinks gracefully.

**Environment**
- OS: macOS 14.0
- Python: 3.11.5
- codebrief: 0.1.0

✨ Requesting Features

We love feature requests! Please check existing feature requests first.

Feature Request Guidelines

  • Clear Use Case: Explain the problem you're trying to solve
  • Proposed Solution: Describe your ideal solution
  • Alternatives: Consider alternative approaches
  • Implementation: Suggest how it might be implemented
  • Breaking Changes: Note any potential breaking changes

🔄 Development Workflow

Branching Strategy

  1. Create a Feature Branch

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

  2. Make Your Changes

  3. Write code following our coding standards
  4. Add tests for new functionality

  5. Update documentation as needed

  6. Test Your Changes

    # Run the full test suite
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/codebrief --cov-report=html

# Run pre-commit checks
poetry run pre-commit run --all-files

  7. Commit Your Changes

    # Use conventional commit format
git commit -m "feat: add support for YAML configuration files"
git commit -m "fix: handle symlinks in tree generation"
git commit -m "docs: update installation instructions"

📏 Coding Standards

We maintain high code quality standards using automated tools:

Code Style

  • Formatter: Ruff for consistent formatting
  • Linter: Ruff for code quality and style enforcement
  • Line Length: 88 characters maximum
  • Quotes: Double quotes for strings
  • Imports: Sorted and organized automatically

Code Quality Tools

# Format code
poetry run ruff format

# Lint code
poetry run ruff check

# Fix auto-fixable issues
poetry run ruff check --fix

# Security scanning
poetry run bandit -r src/

Conventional Commits

We use Conventional Commits for clear commit history:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • test: - Test additions or modifications
  • refactor: - Code refactoring
  • chore: - Maintenance tasks
  • ci: - CI/CD changes

Examples:

feat(tree): add support for custom tree symbols
fix(bundler): resolve encoding issues with non-UTF8 files
docs: add examples for advanced configuration
test: improve coverage for git provider module

Type Hints

  • Use type hints for all function parameters and return values
  • Import types from typing module when needed
  • Use Optional[T] for nullable values
  • Document complex types in docstrings

Documentation

  • Docstrings: Use Google-style docstrings for all public functions
  • Comments: Explain complex logic and business decisions
  • README: Update README.md for user-facing changes
  • API Docs: Update API documentation for new features

🧪 Testing Guidelines

Test Structure

tests/
├── tools/           # Tool-specific tests
├── utils/           # Utility function tests
├── conftest.py      # Shared test fixtures
└── test_main.py     # CLI integration tests

Writing Tests

  1. Test Coverage: Aim for 80%+ coverage for new code
  2. Test Types:
  3. Unit tests for individual functions
  4. Integration tests for CLI commands

  5. Edge case testing for error conditions

  6. Test Naming: Use descriptive test names 

    def test_tree_generator_handles_permission_errors():
    """Test that tree generation gracefully handles permission errors."""

  7. Fixtures: Use pytest fixtures for common test data

  8. Assertions: Prefer content-based assertions over brittle snapshot tests

Running Tests

# Run all tests
poetry run pytest

# Run specific test file
poetry run pytest tests/tools/test_tree_generator.py

# Run with coverage
poetry run pytest --cov=src/codebrief --cov-report=html

# Run tests matching a pattern
poetry run pytest -k "test_tree"

🔄 Pull Request Process

Before Submitting

  1. Update Documentation: Ensure all documentation is current
  2. Add Tests: Include tests for new functionality
  3. Run Quality Checks: Ensure all pre-commit hooks pass
  4. Update Changelog: Add entry to CHANGELOG.md if applicable

PR Guidelines

  1. Clear Title: Use conventional commit format
  2. Detailed Description: Explain what and why
  3. Link Issues: Reference related issues with Fixes #123
  4. Small PRs: Keep changes focused and reviewable
  5. Draft PRs: Use draft PRs for work-in-progress

PR Template

We provide a PR template that includes:

  • Description of changes
  • Type of change (bug fix, feature, etc.)
  • Testing checklist
  • Documentation updates
  • Breaking changes

Review Process

  1. Automated Checks: All CI checks must pass
  2. Code Review: At least one maintainer review required
  3. Testing: Reviewers will test functionality
  4. Documentation: Ensure docs are clear and complete
  5. Merge: Maintainers will merge approved PRs

🚀 Release Process

Version Management

Release Checklist

  1. Update version in pyproject.toml
  2. Update CHANGELOG.md
  3. Create release PR
  4. Tag release after merge
  5. Publish to PyPI (maintainers only)

🆘 Getting Help

Communication Channels

  • GitHub Issues: For bugs and feature requests
  • GitHub Discussions: For questions and general discussion
  • Documentation: Check our comprehensive docs

Maintainer Contact

For sensitive issues or questions, contact the maintainers directly through GitHub.

🎉 Recognition

Contributors are recognized in:

  • CHANGELOG.md for significant contributions
  • GitHub contributors page
  • Release notes for major features

Thank you for contributing to codebrief! Your efforts help make this tool better for the entire developer community. 🚀