Contributing to Taskdog¶

Thank you for your interest in contributing to Taskdog! We welcome contributions of all kinds, including:

Bug reports and fixes
Feature requests and implementations
Documentation improvements
Code optimizations and refactoring
Test coverage improvements

This guide will help you get started with contributing to the project.

Development Setup¶

Prerequisites¶

Python 3.11+ (workspace root) / Python 3.13+ (individual packages)
uv - Python package manager
Git

Installation¶

Clone the repository:

git clone https://github.com/<your-username>/taskdog.git
cd taskdog

Install with development dependencies:

make install-dev

This installs all packages with development dependencies in editable mode and automatically sets up pre-commit hooks (pre-commit, commit-msg, pre-push, post-merge) via uv run pre-commit install.

Verify installation:

# Run all tests
make test

# Run linter
make lint

# Run type checker
make typecheck

Alternative Installation Methods¶

# Install locally for development (per-package editable mode)
make install-local

# Install as global commands (via uv tool)
make install

Project Structure¶

Taskdog is a UV workspace monorepo with three packages:

taskdog/
├── packages/
│   ├── taskdog-core/      # Core business logic and infrastructure
│   │   ├── src/taskdog_core/
│   │   │   ├── domain/           # Entities, services, exceptions
│   │   │   ├── application/      # Use cases, queries, DTOs, validators
│   │   │   ├── infrastructure/   # SQLite repository, config
│   │   │   └── controllers/      # CRUD, Lifecycle, Relationship, Analytics, Query controllers
│   │   └── tests/
│   ├── taskdog-server/    # FastAPI REST API server
│   │   ├── src/taskdog_server/
│   │   │   ├── api/              # Routers, models, dependencies
│   │   │   └── main.py           # FastAPI application
│   │   └── tests/
│   └── taskdog-ui/        # CLI and TUI interfaces
│       ├── src/taskdog/
│       │   ├── cli/              # Click commands
│       │   ├── tui/              # Textual TUI
│       │   ├── console/          # Output formatters
│       │   └── renderers/        # Table and Gantt renderers
│       └── tests/
├── pyproject.toml         # Workspace configuration
├── CLAUDE.md              # Detailed architecture documentation
└── Makefile               # Build and test automation

Package Dependencies¶

taskdog-core: No dependencies on other packages (pure business logic)
taskdog-server: Depends on taskdog-core (direct access to controllers and repository)
taskdog-ui: Depends on taskdog-core (for DTOs and types; accesses data via HTTP API)

Communication Flow¶

CLI/TUI (taskdog-ui) → HTTP API → FastAPI (taskdog-server) → Controllers/Repository (taskdog-core)

Architecture¶

Taskdog follows Clean Architecture principles. For detailed architecture documentation, see CLAUDE.md.

Coding Standards¶

This project enforces high code quality standards:

Linting and Formatting¶

Linter: Ruff
Formatter: Ruff format
Line Length: 88 characters
McCabe Complexity: Max 10

# Run linter
make lint

# Auto-format code
make format

# Run both
make check

Type Checking¶

Type Checker: mypy (Phase 4 - strict mode)
All code must have proper type annotations

# Run type checker
make typecheck

Code Quality Commands¶

# Run all quality checks (lint + typecheck)
make check

# Auto-format code before committing
make format

Testing¶

Test Framework¶

Framework: pytest (with pytest-cov, pytest-asyncio)
Coverage Tool: pytest-cov

Writing Tests¶

Write tests for all new features and bug fixes
Test structure mirrors package structure under tests/
Use unittest.mock for dependencies
Follow existing test patterns in the codebase

Running Tests¶

# Run all tests (core + server + ui)
make test

# Run tests for specific package
make test-core
make test-server
make test-ui

# All test commands include coverage (sorted by coverage: low → high)

# Run single test file (from package directory)
cd packages/taskdog-core && PYTHONPATH=src uv run python -m pytest tests/test_module.py -v

# Run specific test method
cd packages/taskdog-core && PYTHONPATH=src uv run python -m pytest tests/test_module.py::TestClass::test_method -v

Coverage Requirements¶

Coverage reports are displayed in CI logs
Focus on improving low-coverage areas
All CI checks must pass before merging

Commit Guidelines¶

This project uses Conventional Commits format:

<type>: <description>

[optional body]

[optional footer]

Commit Types¶

feat: - New feature
fix: - Bug fix
docs: - Documentation only
refactor: - Code refactoring (no functional changes)
test: - Adding or updating tests
chore: - Maintenance tasks (dependencies, tooling)
perf: - Performance improvements
style: - Code style changes (formatting, whitespace)

Examples¶

feat: Add genetic algorithm for schedule optimization
fix: Fix circular dependency detection in optimizer
docs: Update API documentation for lifecycle endpoints
refactor: Extract common validation logic to base class
test: Add tests for WorkloadCalculator edge cases
chore: Update dependencies to latest versions

Pull Request Process¶

1. Fork and Clone¶

# Fork the repository on GitHub
git clone https://github.com/YOUR_USERNAME/taskdog.git
cd taskdog
git remote add upstream https://github.com/Kohei-Wada/taskdog.git

2. Create a Feature Branch¶

git checkout -b feature/my-feature
# or
git checkout -b fix/bug-description

3. Make Your Changes¶

Write clean, well-documented code
Follow the coding standards
Add tests for your changes
Update documentation if needed

4. Test Your Changes¶

# Run all quality checks
make check

# Run all tests with coverage
make test

5. Commit Your Changes¶

# Stage your changes
git add .

# Commit with conventional commit format
git commit -m "feat: Add my awesome feature"

6. Push to Your Fork¶

git push origin feature/my-feature

7. Create a Pull Request¶

Go to GitHub and create a Pull Request from your branch
Fill in the PR template (if available)
Reference any related issues (e.g., "Closes #123")

PR Checklist¶

Before submitting your PR, ensure:

[ ] Tests pass (make test)
[ ] Linter passes (make lint)
[ ] Type checker passes (make typecheck)
[ ] Code is formatted (make format)
[ ] Documentation updated (if needed)
[ ] CHANGELOG.md updated (if user-facing change)
[ ] Commit messages follow conventional commit format

CI Checks¶

All pull requests automatically run:

Linting (make lint)
Type checking (make typecheck)
Tests with coverage (make test)

All checks must pass before merging.

Development Workflow¶

Per-Package Development¶

When working on a specific package:

# Core package
cd packages/taskdog-core
make install-core
make test-core

# Server package
cd packages/taskdog-server
make install-server
make test-server

# UI package
cd packages/taskdog-ui
make install-ui
make test-ui

Running During Development¶

# Run CLI without installation
cd packages/taskdog-ui
PYTHONPATH=src uv run python -m taskdog.cli_main --help

# Run server without installation
cd packages/taskdog-server
PYTHONPATH=src uv run python -m taskdog_server.main --help

Design Philosophy¶

Before adding new features, please review DESIGN_PHILOSOPHY.md. This document explains why Taskdog focuses on individual task management with flat task structures, and includes guidelines for evaluating new feature proposals.

Questions and Support¶

Getting Help¶

Questions: Open an issue with the question label
Bug Reports: Open an issue with the bug label
Feature Requests: Open an issue with the enhancement label

Before Opening an Issue¶

Search existing issues to avoid duplicates
Check the documentation (README.md, CLAUDE.md)
Try reproducing the issue with the latest version

Issue Templates¶

When opening an issue, please provide:

Bug Reports: Steps to reproduce, expected vs actual behavior, environment details
Feature Requests: Clear use case, proposed solution, alternatives considered
Questions: Context, what you've tried, relevant code/commands

Code of Conduct¶

We are committed to providing a welcoming and inclusive environment for all contributors. Please:

Be respectful and constructive in discussions
Focus on the technical merits of ideas
Welcome newcomers and help them get started
Assume good intentions

License¶

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

Additional Resources¶

CLAUDE.md - Detailed architecture and development guide
DESIGN_PHILOSOPHY.md - Design principles and rationale
README.md - User documentation and features
Conventional Commits - Commit message format
UV Documentation - Package manager guide

Thank you for contributing to Taskdog! 🐕