Contributing¶

Guide to contributing to ebk.

We welcome contributions! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your help is appreciated.

Development Setup¶

Prerequisites¶

Python 3.10 or higher
Git
(Optional) Ollama for LLM features

Setup Steps¶

# Clone the repository
git clone https://github.com/queelius/ebk.git
cd ebk

# Create virtual environment and install dependencies
make setup

# Or manually:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev,all]"

Running Tests¶

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific test file
pytest tests/test_library_api.py -v

# Run unit tests only
pytest -m unit

# Run integration tests only
pytest -m integration

Code Quality¶

# Run linters
make lint

# Format code
make format

# Check formatting
make format-check

Making Changes¶

Create a branch for your changes:
```
git checkout -b feature/my-new-feature
```
Make your changes following the project style:
Use type hints
Add docstrings to public APIs
Follow PEP 8 style guide
Keep functions focused and small
Write tests for new functionality:
Add unit tests in tests/
Aim for >80% code coverage
Test edge cases and error handling
Update documentation:
Update /docs for user-facing changes
Update docstrings for API changes
Add examples for new features

Commit your changes:

git add .
git commit -m "Add feature: brief description"

Push and create PR:
```
git push origin feature/my-new-feature
```
Then create a pull request on GitHub.

Project Structure¶

ebk/
├── ebk/                    # Main package
│   ├── ai/                # AI/LLM features
│   ├── db/                # Database models
│   ├── services/          # Business logic
│   ├── cli.py            # CLI commands
│   ├── server.py         # Web server
│   └── config.py         # Configuration
├── tests/                 # Test suite
├── docs/                  # Documentation
└── integrations/          # Optional integrations

Code Style Guidelines¶

Type Hints: Use type hints for all function signatures
Docstrings: Use Google-style docstrings
Naming:
snake_case for functions and variables
PascalCase for classes
UPPER_CASE for constants
Line Length: Maximum 100 characters
Imports: Group standard library, third-party, and local imports

Adding New Features¶

Adding an LLM Provider¶

Create new file in ebk/ai/llm_providers/
Subclass BaseLLMProvider
Implement required methods
Add tests in tests/ai/
Update documentation

Example:

from .base import BaseLLMProvider, LLMResponse

class MyProvider(BaseLLMProvider):
    @property
    def name(self) -> str:
        return "my_provider"

    async def complete(self, prompt: str, **kwargs) -> LLMResponse:
        # Implementation
        pass

Adding a CLI Command¶

Add command function in ebk/cli.py
Use @app.command() decorator
Add type hints and help text
Load config defaults when appropriate
Update docs/user-guide/cli.md

Adding Documentation¶

Add markdown files to appropriate /docs subdirectory
Update mkdocs.yml navigation
Follow existing documentation style
Include code examples
Test with mkdocs serve

Reporting Issues¶

When reporting bugs, please include:

ebk version (ebk --version)
Python version
Operating system
Steps to reproduce
Expected vs actual behavior
Error messages and stack traces

Feature Requests¶

For feature requests, please describe:

The use case
Why existing features don't suffice
Proposed API or interface
Any implementation ideas

Questions?¶

Open an issue on GitHub
Check existing documentation
Review architecture documentation

License¶

By contributing, you agree that your contributions will be licensed under the project's MIT License.