62 lines
1.9 KiB
Markdown
62 lines
1.9 KiB
Markdown
# 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.
|