Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (75 loc) · 2.34 KB

CONTRIBUTING.md

File metadata and controls

109 lines (75 loc) · 2.34 KB

Contributing to AnimaWorks

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

Development Setup

Prerequisites

  • Python 3.12+
  • uv (recommended) or pip

Clone and Install

git clone https://github.com/xuiltul/animaworks.git
cd animaworks

# Using uv (recommended)
uv sync

# Or using pip
python -m venv .venv
source .venv/bin/activate
pip install -e ".[all-tools,test]"

Start the Server

python main.py start --host 0.0.0.0 --port 18500

Running Tests

# Run unit tests (fast, no external services)
pytest tests/unit/ -x -q -m "not live and not azure and not ollama"

# Run full test suite
pytest

# Run with coverage
pytest --cov=core --cov=server

Linting

We use Ruff for linting and formatting:

# Check for lint errors
ruff check core/ cli/ server/

# Auto-fix lint errors
ruff check core/ cli/ server/ --fix

# Format code
ruff format core/ cli/ server/

Configuration: pyproject.toml — line length 120, target Python 3.12.

Code Style

  • from __future__ import annotations at the top of every file
  • Type hints required (str | None style)
  • Google-style docstrings
  • logger = logging.getLogger(__name__)

Finding Issues

Look for issues labeled good first issue — these are great starting points for new contributors.

Pull Request Process

Branch Naming

Use descriptive branch names:

  • fix/issue-42-fix-theme-toggle
  • feat/add-health-endpoint
  • docs/improve-contributing

Commit Messages

Use semantic commit prefixes:

  • feat: — new feature
  • fix: — bug fix
  • refactor: — code restructuring
  • docs: — documentation changes
  • test: — adding or updating tests

PR Checklist

  1. Create a feature branch from main
  2. Add tests for new functionality
  3. Run pytest and ensure all tests pass
  4. Run ruff check and ruff format — no lint errors
  5. Submit a PR with a clear description of what changed and why
  6. Reference the issue: Fixes #N or Closes #N

License Headers

All source files must include the Apache 2.0 header:

# AnimaWorks - Digital Anima Framework
# Copyright (C) 2026 AnimaWorks Authors
# SPDX-License-Identifier: Apache-2.0