git-activity-merger/AGENTS.md

AGENTS.md

Repository guidance for agents working in git-activity-merge.

Project Snapshot

• FastAPI service that merges GitHub and Gitea contribution data.
• Main outputs are JSON, SVG, and PNG at /activity.json, /activity.svg, and /activity.png.
• Source code lives in app/; tests live in tests/.

Setup

• Python requirement: >=3.11.
• Install dependencies with:
  • pip install -e ".[dev]"
• Configure runtime settings through environment variables or .env.
• Required env vars:
  • GITHUB_USERNAME
  • GITEA_BASE_URL
  • GITEA_USERNAME
• Optional env vars:
  • GITHUB_TOKEN
  • GITEA_TOKEN
  • CACHE_DIR
  • CACHE_TTL_SECONDS
  • DEFAULT_THEME
  • SERVICE_TITLE

Common Commands

• Run tests:
  • pytest -q
• Run the app locally:
  • uvicorn app.main:app --reload --port 8000
• Build the container image:
  • docker build -t git-activity-merge .
• Run with Compose:
  • docker compose up --build

Code Layout

• app/main.py wires routes, caching, and response rendering.
• app/merge.py normalizes and merges activity counts.
• app/settings.py defines environment-backed configuration.
• app/sources/ contains GitHub and Gitea fetchers.
• app/render/ contains SVG and PNG rendering helpers.

Testing Notes

• CI runs pytest -q on Ubuntu with Python 3.12.
• Prefer focused tests in tests/ when changing behavior.
• If you touch API behavior, update or add route tests in tests/test_routes.py.
• If you change merge logic, add coverage in tests/test_merge.py.
• If you change cache behavior, add coverage in tests/test_cache.py.

Editing Rules

• Keep changes aligned with the existing minimal FastAPI structure.
• Avoid introducing new dependencies unless they clearly reduce complexity or fix a real gap.
• Do not commit secrets or real production environment values.
• Prefer small, targeted changes over broad refactors unless the user asked for one.