command-assistant/docs/developer/contributing.md

Contributing Guidelines

Thank you for your interest in contributing to Edison! This guide will help you get started with contributing to the project.

Development Workflow

gitGraph
    commit id: "Initial setup"
    branch feature/my-feature
    checkout feature/my-feature
    commit id: "Implement feature"
    commit id: "Add tests"
    commit id: "Fix bugs"
    checkout main
    merge feature/my-feature
    commit id: "Release v1.0.1"

Getting Started

Setting Up Your Development Environment

1. Fork the repository:

   • Visit the GitHub repository and click the "Fork" button

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/command-assistant.git
   cd command-assistant
   

3. Set up a virtual environment:

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

4. Install in development mode:

   pip install -e .
   

5. Install development dependencies:

   pip install pylint pytest
   

Development Process

1. Create a branch:

   git checkout -b feature/my-feature-name
   

2. Make your changes:

   • Write code
   • Add tests
   • Update documentation

3. Run tests and linting:

   # Run tests (future addition)
   pytest
   
   # Run linting
   pylint edison
   

4. Commit your changes:

   git add .
   git commit -m "Descriptive commit message"
   

5. Push to your fork:

   git push origin feature/my-feature-name
   

6. Submit a pull request:

   • Go to your fork on GitHub
   • Click "New Pull Request"
   • Select your branch and submit

Code Style and Guidelines

Python Style Guide

Edison follows PEP 8 with some additional guidelines:

• Use 4 spaces for indentation
• Maximum line length of 100 characters
• Use meaningful variable and function names
• Write docstrings for all classes and functions

Docstring Format

We use Google-style docstrings:

def example_function(param1, param2):
    """
    Brief description of the function.
    
    Args:
        param1: Description of param1
        param2: Description of param2
        
    Returns:
        Description of return value
        
    Raises:
        ExceptionType: When and why this exception is raised
    """
    pass

Code Organization

• Keep functions focused on a single responsibility
• Group related functionality in modules
• Use appropriate error handling
• Add useful log messages

Adding New Features

When adding new features:

1. Start by discussing: Open an issue to discuss your proposed feature
2. Design the interface: How will users interact with your feature?
3. Plan the implementation: Sketch out the implementation before coding
4. Write tests: Add tests to verify your feature works correctly
5. Document the feature: Update or add documentation explaining the feature
6. Submit for review: Submit a pull request for review

Release Process

flowchart TD
    A[Feature Development] --> B[Testing]
    B --> C[Code Review]
    C --> D{Approved?}
    D -->|No| B
    D -->|Yes| E[Merge to Main]
    E --> F[Version Bump]
    F --> G[Release]
    
    style A fill:#f9d5e5,stroke:#333,stroke-width:2px
    style B fill:#eeeeee,stroke:#333,stroke-width:2px
    style C fill:#d3f6db,stroke:#333,stroke-width:2px
    style D fill:#d3f6f5,stroke:#333,stroke-width:2px
    style E fill:#f5d5f5,stroke:#333,stroke-width:2px
    style F fill:#f5d5d5,stroke:#333,stroke-width:2px
    style G fill:#d5d5f5,stroke:#333,stroke-width:2px

Edison follows semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Incompatible API changes
• MINOR: Backwards-compatible new features
• PATCH: Backwards-compatible bug fixes

Future Development Areas

We're looking for contributions in these areas:

1. Testing Framework: Adding a comprehensive test suite
2. Documentation: Expanding and improving documentation
3. Supported Shells: Adding support for additional shells
4. Platform Support: Enhancing cross-platform compatibility
5. Model Support: Adding support for alternative AI models
6. Command Validation: Improving safety checks
7. Interactive Features: Enhancing the interactive shell
8. Performance Optimization: Improving response times

Best Practices

Security Considerations

• Never commit API keys or sensitive information
• Validate user input thoroughly
• Use safe subprocess execution methods
• Be careful with permissions and file operations

Performance

• Minimize API calls where possible
• Use efficient algorithms and data structures
• Avoid unnecessary file I/O
• Profile code to identify bottlenecks

User Experience

• Provide clear feedback to users
• Use consistent command-line interfaces
• Add helpful error messages
• Consider accessibility in your design

Getting Help

If you need help with contributing:

• Open an issue on GitHub
• Check existing documentation
• Reach out to maintainers

Thank you for contributing to Edison!