Contributing¶

Thank you for your interest in contributing to faker-news! This guide will help you get started.

Development Setup¶

1. Clone the Repository¶

git clone https://github.com/smileychris/faker-news.git
cd faker-news

2. Install Dependencies¶

Install the package in development mode with all dependencies:

pip install -e ".[dev]"

This installs: - Core dependencies (faker, openai, click, etc.) - Development tools (pytest, ruff) - Documentation tools (mkdocs, mkdocs-material)

3. Configure API Key¶

Run the setup wizard to configure your LLM API key:

uv run faker-news setup

Or set environment variables:

export OPENAI_API_KEY="your-api-key"

4. Verify Installation¶

Run the tests to verify everything works:

uv run pytest

Development Workflow¶

Running Tests¶

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=faker_news --cov-report=html

# Run specific test file
uv run pytest tests/test_provider.py

# Run verbose
uv run pytest -v

# Skip slow/integration tests
uv run pytest -m "not integration and not slow"

Code Formatting¶

We use Ruff for code formatting:

# Format all code
ruff format src/ tests/

# Check without modifying
ruff format --check src/ tests/

Linting¶

We use Ruff for linting:

# Lint code
ruff check src/ tests/

# Auto-fix issues
ruff check --fix src/ tests/

Building Documentation¶

Build and preview the documentation locally:

# Install docs dependencies
pip install -e ".[docs]"

# Serve docs locally
mkdocs serve

# Build docs
mkdocs build

Then visit http://localhost:8000 to view the docs.

Code Guidelines¶

Code Style¶

Follow PEP 8 conventions
Use type hints for all public APIs
Maximum line length: 120 characters
Use Ruff for formatting (automated)

Documentation¶

Add docstrings to all public functions/classes
Include examples in docstrings
Update relevant documentation when changing APIs
IMPORTANT: When changing APIs, update:
docs/api-reference.md - For Python API changes
docs/cli-reference.md - For CLI command changes
Other relevant docs as needed

Testing¶

Write tests for all new features
Maintain or improve code coverage
Use pytest fixtures for common setup
Mark slow tests with @pytest.mark.slow
Mark integration tests with @pytest.mark.integration

Example Test¶

import pytest
from faker import Faker
from faker_news import NewsProvider


def test_news_headline(fake):
    """Test headline generation."""
    fake.add_provider(NewsProvider(fake))

    headline = fake.news_headline()

    assert isinstance(headline, str)
    assert len(headline) > 0


@pytest.mark.integration
def test_full_article_generation(fake):
    """Test complete article generation (requires API key)."""
    fake.add_provider(NewsProvider(fake))

    headline = fake.news_headline()
    intro = fake.news_intro(headline=headline)
    article = fake.news_article(headline=headline)

    assert headline in intro or intro.startswith(headline)
    assert len(article) > len(intro)

Project Structure¶

faker-news/
├── src/faker_news/
│   ├── __init__.py       # Public API exports
│   ├── client.py         # LLMClient and LLMClientConfig
│   ├── store.py          # NewsStore (SQLite layer)
│   ├── provider.py       # NewsProvider (Faker provider)
│   ├── cli.py            # Command-line interface
│   └── setup.py          # Interactive setup script
├── tests/
│   ├── conftest.py       # Shared fixtures
│   ├── test_client.py    # LLMClient tests
│   ├── test_store.py     # NewsStore tests
│   ├── test_provider.py  # NewsProvider tests
│   └── test_cli.py       # CLI tests
├── docs/                 # MkDocs documentation
│   ├── index.md
│   ├── getting-started.md
│   ├── api-reference.md
│   └── ...
├── pyproject.toml        # Project configuration
├── mkdocs.yml            # Documentation configuration
├── README.md             # Quick reference
└── CLAUDE.md             # Developer guide (for Claude Code)

Making Changes¶

1. Create a Branch¶

git checkout -b feature/your-feature-name

2. Make Your Changes¶

Write code following the guidelines above
Add tests for new functionality
Update documentation if needed
Format code with Black
Lint code with Ruff

3. Run Tests¶

# Run all tests
uv run pytest

# Check coverage
uv run pytest --cov=faker_news

4. Commit Your Changes¶

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

Use conventional commit messages: - feat: - New feature - fix: - Bug fix - docs: - Documentation changes - test: - Test changes - refactor: - Code refactoring - chore: - Maintenance tasks

5. Push and Create PR¶

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Areas for Contribution¶

Features¶

Support for additional LLM providers
New content types (summaries, captions, etc.)
Advanced caching strategies
Performance optimizations
CLI enhancements

Documentation¶

More usage examples
Tutorials for specific use cases
Translation to other languages
Video walkthroughs
API documentation improvements

Testing¶

Increase test coverage
Add integration tests
Performance benchmarks
Stress tests

Bug Fixes¶

Check the issues page for reported bugs.

Reporting Issues¶

Bug Reports¶

When reporting bugs, include:

Description: What happened vs. what you expected
Steps to reproduce: Exact steps to trigger the bug
Environment:
Python version
faker-news version
Operating system
LLM provider being used
Code sample: Minimal code to reproduce the issue
Error messages: Full error output

Feature Requests¶

When requesting features, include:

Use case: Why you need this feature
Proposed solution: How you envision it working
Alternatives: Other approaches you've considered
Examples: Similar features in other tools

Code Review Process¶

Automated checks: CI runs tests and linting
Manual review: Maintainer reviews code
Feedback: Suggestions for improvements
Approval: Once approved, PR is merged

Release Process¶

Releases are managed by maintainers:

Update version in pyproject.toml
Update CHANGELOG.md
Create git tag
Build distribution: python -m build
Publish to PyPI: twine upload dist/*
Create GitHub release

Community Guidelines¶

Be respectful and inclusive
Help others in issues and discussions
Follow the code of conduct
Give credit where due

Getting Help¶

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: smileychris@gmail.com

License¶

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

Recognition¶

Contributors are recognized in: - GitHub contributors page - Release notes - CONTRIBUTORS.md (coming soon)

Thank you for contributing to faker-news! 🎉