photoprism/.github/copilot-instructions.md

Instructions for GitHub Copilot

Purpose

• Provide Copilot with the single sources of truth for building, testing, and contributing to PhotoPrism.
• Improve PR reviews and code suggestions by aligning them with our documented workflows and style.

Single Sources of Truth (SOT)

• Makefile targets (always prefer existing targets): https://github.com/photoprism/photoprism/blob/develop/Makefile
• Developer Guide – Setup: https://docs.photoprism.app/developer-guide/setup/
• Developer Guide – Tests: https://docs.photoprism.app/developer-guide/tests/
• Contributing: https://github.com/photoprism/photoprism/blob/develop/CONTRIBUTING.md
• Security: https://github.com/photoprism/photoprism/blob/develop/SECURITY.md
• REST API (Swagger): https://docs.photoprism.dev/
• REST API Guide: https://docs.photoprism.app/developer-guide/api/
• Agents reference for tools/commands: https://github.com/photoprism/photoprism/blob/develop/AGENTS.md

Build & Run (local dev; use Makefile first)

• Show tasks: make help
• Build local image: make docker-build
• Start dev env: docker compose up (add -d for detached)
• Logs: docker compose logs -f --tail=100 photoprism
• Open app: http://localhost:2342/ (HTTP) / https://app.localssl.dev/ (TLS via Traefik when enabled)
• From the dev container:
  • Install deps: make dep
  • Build frontend: make build-js (or cd frontend && npm run build)
  • Build backend: make build-go
  • Watch frontend: make watch-js (stop with Ctrl+C)
  • Run server binary: ./photoprism start

Tests & Lint

• Full tests: make test
• Frontend tests (Vitest): make test-js (watch: make vitest-watch, coverage: make vitest-coverage)
• Backend tests: make test-go
• Formatting:
  • Go: go fmt, goimports (see make fmt, make fmt-go)
  • JS/Vue: use scripts in frontend/package.json (ESLint + Prettier)

Project Structure & Languages

• Backend: Go (internal/, pkg/, cmd/) + MariaDB/SQLite
• Frontend: Vue 3 + Vuetify 3 (frontend/)
• Docker/compose for dev/CI; Traefik used for local TLS in dev profile when enabled.

Code Review Instructions (for Copilot)

• Respect SOT above; do not invent flags, env vars, or Compose options. If a command/env var is not in the docs/Makefile/CLI help, say “not documented” and suggest checking the SOT.
• Prefer minimal, surgical diffs. Propose changes as concrete patches and reference the relevant Makefile target or doc section.
• Before suggesting refactors, check tests and build tasks exist and can pass with the change. If tests are missing, suggest specific Vitest/Go test snippets.
• Security: never suggest committing secrets; prefer env vars and .env in dev only. Point to SECURITY.md for disclosures.
• Data safety: never run or recommend destructive CLI operations in examples without explicit backups and --yes. Avoid photoprism reset, photoprism users reset, photoprism auth reset, or photoprism audit reset in PR comments unless the change is specifically about those commands; if unavoidable, add bold warnings and backup steps.
• Database/schema: if a change touches persistence, check for migrations and mention photoprism migrate / migrations commands.
• API changes: align with the REST API docs/spec; include curl examples only if they match current endpoints and auth notes.
• UX/i18n: keep UI strings concise, translatable, and consistent; avoid hard-coded language constructs; prefer existing patterns/components.

Style & Patterns

• Go: idiomatic Go, clear error handling, small functions, packages with focused responsibilities. Keep public surface minimal. Add/adjust unit tests.
• Vue/JS: options API, store patterns as in existing code, avoid breaking translations. Keep ESLint/Prettier clean.
• Config & flags: suggest photoprism --help, photoprism show config-options or photoprism show config-yaml to verify names before using them.

Performance & Reliability

• Prefer using existing caches, workers, and batching strategies referenced in code and Makefile. Consider memory/CPU impact; suggest benchmarks or profiling only when justified.

When Unsure

• Ask for the exact Makefile target or doc link you need, then proceed. Defer to SOT if any conflict arises.

References To Help Copilot Answer Questions

• Show supported formats/filters: run photoprism show file-formats and photoprism show search-filters (use results rather than guessing).
• For CI/dev containers, assume Linux/Unix shell by default; link Windows specifics in Developer Guide FAQ.

Output Expectations

• Prefer short, actionable comments with code blocks that pass tests locally: make test-js (frontend) / make test-go (backend)
• If a suggestion requires additional context (e.g., DB access, external service), call it out explicitly.

Safety Checklist Before Proposing a CLI Command

• Include a dry-run or non-destructive variant if possible.
• Recommend creating/using backups before any reset/migrate.