Contributing¶

Contributing to elfshoe¶

Thank you for your interest in contributing to elfshoe! This document provides guidelines and instructions for contributing.

🎯 How to Contribute¶

Reporting Bugs¶

1. Check if the bug has already been reported in Issues
2. If not, create a new issue with:
3. Clear, descriptive title
4. Detailed description of the problem
5. Steps to reproduce
6. Expected vs actual behavior
7. Your environment (OS, Python version, package versions)
8. Relevant logs or error messages

Suggesting Enhancements¶

1. Check existing Issues and Pull Requests
2. Create a new issue describing:
3. The enhancement you'd like to see
4. Why it would be useful
5. Possible implementation approaches

Pull Requests¶

1. Fork the repository
2. Clone your fork locally
3. Create a branch for your changes:

git checkout -b feature/my-new-feature

1. Make your changes following our guidelines below
2. Test your changes thoroughly
3. Commit with clear, descriptive messages
4. Push to your fork
5. Submit a pull request to the main repository

🛠️ Development Setup¶

Prerequisites¶

• Python 3.7 or higher
• Git
• Make (optional, but recommended)

Initial Setup¶

# Clone your fork
git clone https://github.com/YOUR_USERNAME/elfshoe.git
cd elfshoe

# Install Hatch
pip install hatch

# Create development environment
hatch env create

# Or use editable install
pip install -e ".[dev]"

# Install pre-commit hooks (recommended)
make pre-commit-install

Pre-commit Hooks¶

This project uses pre-commit hooks to ensure code quality. After installation:

• On commit: Automatically formats code, runs linting, checks docs
• On push: Runs full test suite and verifies package builds

See docs/developer/pre-commit.md for details.

Running Tests¶

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific test file
pytest tests/test_elfshoe.py

# Using hatch
hatch run test
hatch run test-cov

Code Quality¶

# Check code style
make lint

# Auto-format code
make format

# Or with hatch
hatch run lint:check
hatch run lint:format

📝 Code Guidelines¶

Style Guide¶

• Follow PEP 8 style guidelines
• Use Black for formatting (line length: 88)
• Use Ruff for linting
• Write clear, descriptive variable and function names
• Add docstrings for public functions and classes

Code Structure¶

• Keep functions focused and single-purpose
• Use type hints where appropriate
• Avoid deep nesting (max 3-4 levels)
• Extract complex logic into separate functions
• Use dataclasses for data structures

Testing¶

• Write tests for all new features
• Maintain or improve test coverage
• Test both success and failure cases
• Use descriptive test names that explain what is being tested
• Group related tests in test classes

Documentation¶

• Update relevant documentation for your changes
• Add docstrings for new functions/classes
• Update README.md if adding user-facing features
• Include code examples for new features

🔌 Adding New Distributions¶

See adding_distributions.md for detailed instructions on adding support for new operating systems.

Quick Checklist¶

1. Create a metadata fetcher class in src/elfshoe/distributions/
2. Inherit from AbstractMetadataFetcher
3. Implement fetch_versions() method
4. Register in src/elfshoe/distributions/__init__.py
5. Add tests in tests/
6. Update documentation
7. Add example configuration to README

🧪 Testing Checklist¶

Before submitting a pull request, ensure:

• [ ] Pre-commit hooks are installed (make pre-commit-install)
• [ ] All tests pass (make test)
• [ ] Code is formatted (make format)
• [ ] Linting passes (make lint)
• [ ] Coverage hasn't decreased (make test-coverage)
• [ ] Documentation is updated
• [ ] New features have tests
• [ ] Examples work as documented

Note: Pre-commit hooks will automatically check most of these before commit/push.

📋 Commit Messages¶

Write clear, descriptive commit messages:

feat: Add support for Ubuntu metadata fetcher

- Implement UbuntuMetadataFetcher class
- Add tests for Ubuntu version detection
- Update documentation with Ubuntu example

Commit Message Format¶

<type>: <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• test: Adding or updating tests
• refactor: Code refactoring
• style: Code style changes (formatting)
• chore: Maintenance tasks

🚀 Release Process¶

Releases are handled by maintainers:

1. Update version in pyproject.toml
2. Create and tag release
3. Build and publish to PyPI:

hatch build
hatch publish

💡 Need Help?¶

• Check the documentation
• Look at existing code for examples
• Review closed pull requests for similar changes
• Open an issue for questions
• Reach out to maintainers

📜 Code of Conduct¶

• Be respectful and inclusive
• Welcome newcomers
• Focus on constructive feedback
• Assume good intentions
• Help others learn and grow

🎉 Recognition¶

Contributors are recognized in:

• GitHub contributors list
• Project README (for major features)

Thank you for contributing to elfshoe! 🙏