# Contributing to PR Assistant
Thank you for your interest in contributing to PR Assistant! This document provides guidelines and instructions for contributing.
## Code of Conduct
- Be respectful and inclusive
- Welcome newcomers and encourage diverse perspectives
- Focus on constructive feedback
- Maintain professionalism in all interactions
## Getting Started
### Prerequisites
- Python 3.8 or higher
- Git
- OpenRouter API key (for testing)
### Development Setup
1. Fork the repository on GitHub
2. Clone your fork locally:
```bash
git clone https://github.com/YOUR_USERNAME/pr-assistant.git
cd pr-assistant
```
3. Install development dependencies:
```bash
pip install -e ".[dev]"
```
4. Install pre-commit hooks:
```bash
pre-commit install
```
5. Create a feature branch:
```bash
git checkout -b feature/your-feature-name
```
## Development Workflow
### Making Changes
1. **Write tests first** - Follow TDD when possible
2. **Keep changes focused** - One feature/fix per PR
3. **Follow code style** - Use Black for formatting
4. **Add documentation** - Update docstrings and README as needed
5. **Update changelog** - Add entry to CHANGELOG.md
### Code Style
We follow PEP 8 with some modifications:
- Line length: 100 characters (not 80)
- Use Black for automatic formatting
- Use descriptive variable names
- Add type hints where beneficial
- Write docstrings for all public functions/classes
Example:
```python
def process_data(input_data: str, max_length: int = 100) -> Dict[str, Any]:
"""
Process input data and return structured result.
Args:
input_data: The raw input string to process
max_length: Maximum length of output (default: 100)
Returns:
Dictionary containing processed data
Raises:
ValidationError: If input_data is invalid
"""
# Implementation here
pass
```
### Running Tests
Run all tests:
```bash
pytest
```
Run with coverage:
```bash
pytest --cov=pr --cov-report=html
```
Run specific test file:
```bash
pytest tests/test_tools.py
```
Run specific test:
```bash
pytest tests/test_tools.py::TestFilesystemTools::test_read_file
```
### Code Quality Checks
Before committing, run:
```bash
# Format code
black pr tests
# Check linting
flake8 pr tests --max-line-length=100 --ignore=E203,W503
# Type checking
mypy pr --ignore-missing-imports
# Run all checks
pre-commit run --all-files
```
## Project Structure
### Adding New Features
#### Adding a New Tool
1. Implement the tool function in appropriate `pr/tools/*.py` file
2. Add tool definition to `pr/tools/base.py:get_tools_definition()`
3. Add function mapping in `pr/core/assistant.py:execute_tool_calls()`
4. Add function mapping in `pr/autonomous/mode.py:execute_single_tool()`
5. Write tests in `tests/test_tools.py`
6. Update documentation
#### Adding a New Configuration Option
1. Add to default config in `pr/core/config_loader.py`
2. Update config documentation in README.md
3. Add validation if needed in `pr/core/validation.py`
4. Write tests
#### Adding a New Command
1. Add handler to `pr/commands/handlers.py`
2. Update help text in `pr/__main__.py`
3. Write tests
4. Update README.md with command documentation
### Plugin Development
Plugins should be self-contained Python files:
```python
# Plugin structure
def tool_function(args):
"""Implementation"""
pass
def register_tools():
"""Return list of tool definitions"""
return [...]
```
## Testing Guidelines
### Test Organization
- `tests/test_*.py` - Test files matching source files
- `tests/conftest.py` - Shared fixtures
- Use descriptive test names: `test_<function>_<scenario>_<expected_result>`
### Writing Good Tests
```python
def test_read_file_with_valid_path_returns_content(temp_dir):
# Arrange
filepath = os.path.join(temp_dir, "test.txt")
expected_content = "Hello, World!"
write_file(filepath, expected_content)
# Act
result = read_file(filepath)
# Assert
assert expected_content in result
```
### Test Coverage
- Aim for >80% code coverage
- Cover edge cases and error conditions
- Test both success and failure paths
## Documentation
### Docstring Format
Use Google-style docstrings:
```python
def function_name(param1: str, param2: int) -> bool:
"""
Short description of function.
Longer description with more details about what the function
does and how it works.
Args:
param1: Description of param1
param2: Description of param2
Returns:
Description of return value
Raises:
ValueError: Description of when this is raised
"""
pass
```
### Updating Documentation
When adding features, update:
- Function/class docstrings
- README.md
- CHANGELOG.md
- Code comments (where necessary)
## Pull Request Process
### Before Submitting
1. ✅ All tests pass
2. ✅ Code is formatted with Black
3. ✅ Linting passes (flake8)
4. ✅ No type errors (mypy)
5. ✅ Documentation is updated
6. ✅ CHANGELOG.md is updated
7. ✅ Commits are clean and descriptive
### PR Template
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Changes Made
- Change 1
- Change 2
## Testing
- Test scenario 1
- Test scenario 2
## Checklist
- [ ] Tests pass
- [ ] Code formatted with Black
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
```
### Review Process
1. Automated checks must pass
2. At least one maintainer review required
3. Address all review comments
4. Squash commits if requested
5. Maintainer will merge when approved
## Commit Messages
Follow conventional commits:
```
type(scope): subject
body (optional)
footer (optional)
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `style`: Formatting
- `refactor`: Code restructuring
- `test`: Adding tests
- `chore`: Maintenance
Examples:
```
feat(tools): add text analysis tool
fix(api): handle timeout errors properly
docs(readme): update installation instructions
```
## Reporting Bugs
### Bug Report Template
**Description:**
Clear description of the bug
**To Reproduce:**
1. Step 1
2. Step 2
3. See error
**Expected Behavior:**
What should happen
**Actual Behavior:**
What actually happens
**Environment:**
- OS:
- Python version:
- PR Assistant version:
**Additional Context:**
Logs, screenshots, etc.
## Feature Requests
**Feature Description:**
What feature would you like?
**Use Case:**
Why is this needed?
**Proposed Solution:**
How might this work?
**Alternatives:**
Other approaches considered
## Questions?
- Open an issue for questions
- Check existing issues first
- Tag with `question` label
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
---
Thank you for contributing to PR Assistant! 🎉
Reference in New Issue View Git Blame Copy Permalink