Skip to content

Contributing to AI Shell

Thank you for your interest in contributing to AI Shell! This document provides comprehensive guidelines for contributing to the project.

🚀 Getting Started

Prerequisites

  • Python 3.9 or higher
  • Git
  • Basic understanding of command-line tools
  • Familiarity with Python and AsyncIO (for advanced contributions)

Development Setup

  1. Fork and Clone 

    git clone https://github.com/your-username/Ai_shell.git
cd Ai_shell

  2. Create Virtual Environment 

    python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install Dependencies 

    pip install -r requirements.txt
pip install pytest black flake8 pytest-cov

  4. Install in Development Mode 

    pip install -e .

  5. Verify Installation 

    python -m pytest
ai-shell --help

🏗️ Project Architecture

Core Components

ai_shell/
├── main.py         # Application entry point and CLI interface
├── config.py       # Configuration management with YAML support
├── llm.py          # LLM provider abstractions (Gemini, Ollama)
├── executor.py     # Command execution with security validation
└── ui.py           # User interface utilities and formatting

Key Design Patterns

  • Provider Pattern: LLM providers implement a common interface
  • Configuration Management: Centralized config with environment variable support
  • Security Layer: Command validation and user confirmation system
  • Async Architecture: Non-blocking operations for better UX

🔧 Development Workflow

Before Making Changes

  1. Create a Feature Branch 

    git checkout -b feature/your-feature-name

  2. Run Tests 

    python -m pytest -v

  3. Check Code Style 

    black --check ai_shell/ tests/
flake8 ai_shell/ tests/

Making Changes

  1. Follow Code Style
  2. Use Black for formatting
  3. Follow PEP 8 guidelines
  4. Add type hints where appropriate

  5. Write descriptive docstrings

  6. Write Tests

  7. Add unit tests for new functionality
  8. Maintain high test coverage
  9. Use descriptive test names

  10. Include both positive and negative test cases

  11. Update Documentation

  12. Update README.md if needed
  13. Add docstrings to new functions/classes
  14. Update configuration examples

Testing Guidelines

# Run all tests
python -m pytest

# Run specific test file
python -m pytest tests/test_config.py

# Run with coverage
python -m pytest --cov=ai_shell --cov-report=html

# Run tests in verbose mode
python -m pytest -v -s

Code Quality

# Format code
black ai_shell/ tests/

# Check code style
flake8 ai_shell/ tests/

# Type checking (optional)
mypy ai_shell/

📝 Contribution Types

🐛 Bug Fixes

  1. Report the Bug
  2. Use GitHub Issues
  3. Provide clear reproduction steps
  4. Include system information

  5. Add relevant logs or screenshots

  6. Fix the Bug

  7. Write a failing test first
  8. Implement the minimal fix
  9. Ensure all tests pass
  10. Update documentation if needed

✨ New Features

  1. Propose the Feature
  2. Open a GitHub Issue for discussion
  3. Explain the use case and benefits

  4. Consider the scope and complexity

  5. Implement the Feature

  6. Follow the existing architecture patterns
  7. Add comprehensive tests
  8. Update documentation
  9. Consider backward compatibility

Common Contribution Areas

Adding New LLM Providers

  1. Create a new provider class in llm.py: 

    class NewLLMProvider(LLMProvider):
    def __init__(self, config):
        self.config = config

    async def generate_response(self, prompt, system_prompt=""):
        # Implementation here
        pass

  2. Register the provider in get_llm_provider()

  3. Add configuration options
  4. Write comprehensive tests

Enhancing Security Features

  1. Add new validation rules in executor.py
  2. Update the dangerous commands list
  3. Add configuration options for new security features
  4. Test edge cases thoroughly

Improving User Interface

  1. Add new UI components in ui.py
  2. Ensure consistent styling with existing components
  3. Test across different terminal environments
  4. Consider accessibility

🧪 Testing Strategy

Test Categories

  1. Unit Tests: Individual component testing
  2. Integration Tests: Component interaction testing
  3. End-to-End Tests: Full workflow testing
  4. Security Tests: Validation and safety testing

Writing Good Tests

def test_config_load_from_file():
    """Test that configuration loads correctly from YAML file."""
    # Arrange
    config_data = {"llm": {"provider": "gemini"}}

    # Act
    config = Config(config_data)

    # Assert
    assert config.get("llm.provider") == "gemini"

Test Coverage

  • Aim for >90% test coverage
  • Focus on critical paths and edge cases
  • Mock external dependencies (APIs, file system)
  • Test error conditions and recovery

📚 Documentation

Code Documentation

  • Docstrings: All public functions and classes
  • Type Hints: Use for better IDE support
  • Comments: Explain complex logic, not obvious code

User Documentation

  • README.md: Keep updated with new features
  • Configuration: Document all config options
  • Examples: Provide practical usage examples

🎯 Commit Guidelines

Commit Message Format

type(scope): brief description

Detailed explanation of the change, including:
- Why the change was made
- What was changed
- Any breaking changes or migration notes

Fixes #123

Commit Types

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring without feature changes
  • test: Adding or updating tests
  • chore: Build process or auxiliary tool changes

Examples

feat(llm): add support for Claude API

- Implement ClaudeProvider class
- Add configuration options for Claude
- Update provider selection logic
- Add comprehensive tests

Fixes #456

fix(security): prevent command injection in user input

- Sanitize user input before processing
- Add validation for special characters
- Update security tests
- Document security considerations

Closes #789

🚢 Release Process

Pull Request Guidelines

  1. Before Submitting
  2. Ensure all tests pass
  3. Update documentation
  4. Add changelog entry

  5. Squash commits if needed

  6. PR Description

  7. Clear title and description
  8. Link to related issues
  9. Include screenshots for UI changes

  10. List breaking changes

  11. Review Process

  12. Address reviewer feedback
  13. Keep discussions focused
  14. Be open to suggestions

Versioning

We follow Semantic Versioning: - MAJOR.MINOR.PATCH - Major: Breaking changes - Minor: New features, backward compatible - Patch: Bug fixes, backward compatible

🤝 Community Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Help others learn and grow
  • Follow the project's coding standards
  • Focus on the problem, not the person

Getting Help

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and ideas
  • Code Review: Learn from feedback and review others' code

🎉 Recognition

Contributors are recognized in: - GitHub contributor graphs - Release notes for significant contributions - Special mentions for outstanding contributions

Thank you for contributing to AI Shell! 🚀