# Contributing to AI Skill Manager

Thank you for your interest in contributing to AI Skill Manager! This document provides guidelines and information for contributors.

## Development Setup

### Prerequisites

- Python 3.8+ with [uv](https://docs.astral.sh/uv/) package manager
- Node.js 16+ with npm
- Git

### Quick Start

```bash
# Clone the repository
git clone https://github.com/yourusername/ai-skill-manager.git
cd ai-skill-manager

# Set up development environment
make dev-setup

# Run tests to ensure everything works
make test
```

## Development Workflow

### Making Changes

1. **Fork the repository** and create a new branch from `main`
2. **Make your changes** following the coding standards
3. **Add tests** for any new functionality
4. **Run the test suite** to ensure nothing is broken
5. **Update documentation** if needed
6. **Submit a pull request**

### Branch Naming

Use descriptive branch names:
- `feature/add-new-command` for new features
- `fix/handle-git-errors` for bug fixes
- `docs/update-readme` for documentation updates
- `refactor/improve-error-handling` for refactoring

### Commit Messages

Follow conventional commit format:
- `feat: add selective download command`
- `fix: handle network timeouts properly`
- `docs: update installation instructions`
- `test: add property tests for git handler`
- `refactor: simplify error handling logic`

## Code Standards

### Python

- Follow PEP 8 style guidelines
- Use type hints for all functions and methods
- Write docstrings for public functions
- Use `ruff` for linting and formatting
- Use `mypy` for type checking

```bash
# Check Python code
make lint
make type-check
```

### TypeScript

- Follow TypeScript best practices
- Use explicit types where beneficial
- Write JSDoc comments for public APIs
- Use ESLint for linting

```bash
# Check TypeScript code
npm run lint
npm run type-check
```

## Testing

### Test Types

1. **Unit Tests**: Test individual functions and classes
2. **Property-Based Tests**: Test universal properties with random inputs
3. **Integration Tests**: Test end-to-end functionality
4. **CLI Tests**: Test command-line interface

### Writing Tests

#### Python Tests
```python
# Unit test example
def test_git_command_generation():
    handler = GitHandler()
    cmd = handler.build_clone_command("https://github.com/user/repo", "/tmp/test")
    assert "git clone" in cmd

# Property-based test example
from hypothesis import given, strategies as st

@given(st.text(), st.text())
def test_skill_path_validation(repo_url, skill_path):
    # Test that skill path validation works for any input
    result = validate_skill_path(repo_url, skill_path)
    assert isinstance(result, bool)
```

#### TypeScript Tests
```typescript
// Unit test example
describe('GitHandler', () => {
  test('should build clone command correctly', () => {
    const handler = new GitHandler();
    const cmd = handler.buildCloneCommand('https://github.com/user/repo', '/tmp/test');
    expect(cmd).toContain('git clone');
  });
});
```

### Running Tests

```bash
# Run all tests
make test

# Run specific test types
make test-python
make test-node

# Run tests with coverage
uv run pytest --cov=ai_skill_manager tests/
npm run test -- --coverage
```

## Documentation

### Code Documentation

- Write clear docstrings for Python functions
- Write JSDoc comments for TypeScript functions
- Include examples in documentation
- Document complex algorithms and business logic

### README Updates

When adding new features:
1. Update the usage examples
2. Add new CLI commands to the documentation
3. Update the feature list
4. Add troubleshooting information if needed

## Pull Request Process

### Before Submitting

1. **Run the full test suite**: `make ci`
2. **Update documentation** as needed
3. **Add changelog entry** if it's a significant change
4. **Test CLI functionality** manually
5. **Ensure all checks pass** in CI

### PR Description

Include in your PR description:
- **What** changes you made
- **Why** you made them
- **How** to test the changes
- **Screenshots** if applicable (for CLI changes)

### Review Process

1. **Automated checks** must pass (CI, linting, tests)
2. **Code review** by maintainers
3. **Manual testing** of new functionality
4. **Documentation review** if applicable

## Release Process

Releases are automated but follow this process:

1. **Update version numbers** in `pyproject.toml` and `package.json`
2. **Update CHANGELOG.md** with new features and fixes
3. **Create and push a git tag**: `git tag v1.0.1 && git push origin v1.0.1`
4. **GitHub Actions** automatically builds and publishes packages

## Getting Help

- **GitHub Issues**: For bug reports and feature requests
- **GitHub Discussions**: For questions and general discussion
- **Code Review**: Ask questions in PR comments

## Code of Conduct

- Be respectful and inclusive
- Focus on constructive feedback
- Help others learn and grow
- Follow the project's coding standards

## Recognition

Contributors will be recognized in:
- GitHub contributors list
- Release notes for significant contributions
- README acknowledgments

Thank you for contributing to AI Skill Manager! 🚀