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

```mermaid
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**:
   ```bash
   git clone https://github.com/YOUR_USERNAME/command-assistant.git
   cd command-assistant
   ```

3. **Set up a virtual environment**:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

4. **Install in development mode**:
   ```bash
   pip install -e .
   ```

5. **Install development dependencies**:
   ```bash
   pip install pylint pytest
   ```

### Development Process

1. **Create a branch**:
   ```bash
   git checkout -b feature/my-feature-name
   ```

2. **Make your changes**:
   - Write code
   - Add tests
   - Update documentation

3. **Run tests and linting**:
   ```bash
   # Run tests (future addition)
   pytest

   # Run linting
   pylint edison
   ```

4. **Commit your changes**:
   ```bash
   git add .
   git commit -m "Descriptive commit message"
   ```

5. **Push to your fork**:
   ```bash
   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](https://www.python.org/dev/peps/pep-0008/) 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:

```python
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

```mermaid
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!