Contributing¶
We welcome contributions to gi! This guide will help you get started.
🚀 Quick Start¶
- Fork the repository
- Clone your fork
- Create a feature branch
- Make your changes
- Test your changes
- Submit a pull request
🛠️ Development Setup¶
Prerequisites¶
- Python 3.10 or higher
- Git
- Basic familiarity with Python development
Installation¶
# Clone your fork
git clone https://github.com/YOUR_USERNAME/gi.git
cd gi
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# Install in development mode
pip install -e ".[dev]"
Verify Installation¶
📝 Development Workflow¶
1. Create Feature Branch¶
# Create and switch to feature branch
git checkout -b feature/your-feature-name
# Or for bug fixes
git checkout -b fix/issue-description
2. Make Changes¶
- Write your code
- Add tests for new functionality
- Update documentation if needed
3. Test Your Changes¶
# Run all tests
python -m pytest tests/ -v
# Run specific test file
python -m pytest tests/test_combine.py -v
# Run with coverage
python -m pytest tests/ --cov=gi --cov-report=term-missing
4. Check Code Quality¶
# Format code
ruff format gi/ tests/
# Check linting
ruff check gi/ tests/
# Type checking (if using mypy)
mypy gi/
5. Commit Changes¶
# Add changes
git add .
# Commit with descriptive message
git commit -m "feat: add new feature description"
# Push to your fork
git push origin feature/your-feature-name
6. Submit Pull Request¶
- Go to your fork on GitHub
- Click "New Pull Request"
- Fill out the template
- Submit the PR
🧪 Testing¶
Running Tests¶
# Run all tests
python -m pytest tests/ -v
# Run specific test
python -m pytest tests/test_combine.py::TestCombineTemplates::test_combine_single_template -v
# Run with coverage
python -m pytest tests/ --cov=gi --cov-report=html
Writing Tests¶
# Example test structure
def test_new_feature():
"""Test description."""
# Arrange
input_data = "test input"
expected_output = "expected result"
# Act
result = function_under_test(input_data)
# Assert
assert result == expected_output
Test Categories¶
- Unit Tests: Test individual functions
- Integration Tests: Test component interactions
- CLI Tests: Test command-line interface
- Network Tests: Test HTTP requests (mocked)
📚 Documentation¶
Code Documentation¶
def example_function(param1: str, param2: int) -> str:
"""Brief description of the function.
Args:
param1: Description of param1
param2: Description of param2
Returns:
Description of return value
Raises:
ValueError: When param2 is negative
"""
pass
User Documentation¶
- Update relevant documentation in
docs/ - Add examples for new features
- Update command reference if needed
🎯 Contribution Areas¶
🐛 Bug Fixes¶
- Fix failing tests
- Resolve issues from GitHub Issues
- Improve error handling
- Fix edge cases
✨ New Features¶
- Add new template aliases
- Improve CLI interface
- Add new commands
- Enhance caching
📖 Documentation¶
- Improve user guides
- Add tutorials
- Update API reference
- Fix typos
🧪 Testing¶
- Add test coverage
- Improve test quality
- Add integration tests
- Performance testing
📋 Pull Request Guidelines¶
Before Submitting¶
- Tests pass locally
- Code follows style guidelines
- Documentation updated
- Commit messages are clear
- Branch is up to date with main
PR Template¶
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Test improvement
- [ ] Other (please describe)
## Testing
- [ ] Tests pass locally
- [ ] New tests added for new functionality
- [ ] All existing tests still pass
## Documentation
- [ ] Documentation updated
- [ ] No breaking changes to public API
🏗️ Building and Testing¶
Local Build¶
# Build executable locally
python scripts/build.py
# Or use the simplified script
bash scripts/build-local.sh
# Test built executable
./dist/*/gi --help
Automation Scripts¶
We provide several automation scripts to streamline development:
- Version Management:
python scripts/bump_version.py [major|minor|patch] - Local Builds:
bash scripts/build-local.sh - Release Management:
python scripts/release.py [command] - Installation:
bash scripts/install.sh
For detailed documentation on all scripts, see Scripts Documentation.
PyPI Publishing¶
The project is automatically published to PyPI when GitHub releases are created. For detailed setup instructions and troubleshooting, see PyPI Publishing Guide.
CI/CD¶
Our GitHub Actions will automatically:
- Run tests on multiple Python versions
- Check code quality
- Build executables
- Deploy documentation
🐛 Reporting Issues¶
Before Reporting¶
- Check existing issues
- Try latest version
- Reproduce the issue
- Gather relevant information
Issue Template¶
## Description
Clear description of the issue
## Steps to Reproduce
1. Step one
2. Step two
3. Step three
## Expected Behavior
What should happen
## Actual Behavior
What actually happens
## Environment
- OS: [e.g., macOS 13.0]
- Python version: [e.g., 3.11.0]
- gi version: [e.g., 0.1.0]
## Additional Context
Any other relevant information
💡 Development Tips¶
1. Use Virtual Environment¶
2. Test Frequently¶
3. Follow Style Guidelines¶
4. Write Good Tests¶
# Test edge cases
def test_edge_case():
"""Test edge case behavior."""
assert function_under_test("") == expected_result
assert function_under_test(None) == expected_result
5. Document Changes¶
# Update docstrings
def new_function(param: str) -> str:
"""New function description.
Args:
param: Parameter description
Returns:
Return value description
"""
pass
🎉 Recognition¶
Contributors will be:
- Listed in the Credits page
- Mentioned in release notes
- Given credit in commit messages
📞 Getting Help¶
- GitHub Issues: For bug reports and feature requests
- GitHub Discussions: For questions and discussions
- Code Review: For feedback on your contributions
📄 License¶
By contributing, you agree that your contributions will be licensed under the same MIT License that covers the project.
Ready to contribute? Check out our Building Guide for more technical details!