Contributing to Yagra

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

For detailed development setup and guidelines, see CONTRIBUTING.md in the repository root.

Quick Start

Prerequisites

  • Python 3.12+

  • uv (recommended package manager)

Setup

git clone https://github.com/shogo-hs/Yagra.git
cd Yagra
uv sync --dev

Run Quality Checks

uv run pre-commit run --all-files

Project Structure

Yagra/
├── src/yagra/          # Source code
│   ├── adapters/       # Inbound/Outbound adapters
│   ├── application/    # Use cases and services
│   ├── domain/         # Domain entities and services
│   ├── ports/          # Port interfaces
│   └── templates/      # Workflow templates
├── tests/              # Test suite
├── examples/           # Example workflows
└── docs/               # Documentation

Development Workflow

  1. Fork and Clone: Fork the repository and clone your fork

  2. Create Branch: git checkout -b feature/my-feature

  3. Make Changes: Implement your feature or fix

  4. Run Tests: uv run pytest

  5. Run Quality Checks: uv run pre-commit run --all-files

  6. Commit: Follow conventional commit format

  7. Push: git push origin feature/my-feature

  8. Create PR: Submit a pull request with clear description

Coding Standards

  • Type Hints: Required for all function signatures

  • Docstrings: Use Google style with Japanese descriptions

  • Formatting: ruff format .

  • Linting: ruff check .

  • Type Checking: mypy .

Testing

# Run all tests
uv run pytest

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

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

Documentation

Building Sphinx Documentation

uv run sphinx-build -b html docs/sphinx/source docs/sphinx/_build/html

Open docs/sphinx/_build/html/index.html in your browser.

Documentation Guidelines

  • Write in English (primary language)

  • Use Markdown (.md) with MyST parser

  • Include code examples for all features

  • Update docstrings for Python API changes

Questions?

License

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