Contributing¶

Guidelines for contributing to Metaseed.

Development Setup¶

Clone the repository:
```
git clone <repository-url>
cd metaseed
```
Install dependencies and pre-commit hooks:
```
make dev
```

Development Workflow¶

Running Tests¶

# Run all tests
make test

# Run with coverage
make test-cov

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

Code Quality¶

Pre-commit hooks run automatically on commit. To run manually:

# Run all hooks
uv run pre-commit run --all-files

# Run ruff linter only
make lint

# Format code
make format

Documentation¶

# Serve docs locally
make docs-serve

# Build docs
make docs

Code Style¶

Follow PEP 8 conventions
Use Google style docstrings
Maximum line length: 100 characters
Use type hints for all function signatures

Commit Messages¶

Use present tense ("add feature" not "added feature")
Keep the first line under 72 characters
Reference issues where applicable

Pull Requests¶

Create a feature branch from main
Make your changes with tests
Ensure all tests pass
Update documentation if needed
Submit a pull request

Project Structure¶

metaseed/
├── src/metaseed/       # Main package
│   ├── api/            # FastAPI routes
│   ├── cli/            # Typer commands
│   ├── core/           # Shared utilities
│   ├── models/         # Pydantic models
│   ├── specs/          # YAML schemas
│   ├── storage/        # Persistence
│   └── validators/     # Validation logic
├── tests/              # Test suite
└── docs/               # Documentation

Exception Handling¶

Exceptions API consumers must catch inherit from MetaseedError in api/errors.py; modules below the API define their own exceptions locally, and the API layer translates them at its boundary. See Exceptions for details.

Where Renovate runs¶

Renovate runs from this repository's own workflow, .github/workflows/renovate.yml: weekly (early Monday, UTC) and on demand from the Actions tab (Renovate > Run workflow), reading renovate.json. The hosted Mend app is installed but has never run on this repository; a workflow here has a visible log and needs nothing enabled elsewhere.

The workflow needs one secret, RENOVATE_TOKEN: a fine-grained personal access token for this repository with read and write access to Contents, Pull requests, Issues, and Workflows. It can't use the workflow's own GITHUB_TOKEN, because pull requests opened with that token trigger no other workflows — the CI gate would never run on an update and nothing could auto-merge. If the hosted app starts running as well, disable one of the two, or every update arrives twice.