Comparison

A · Copilot instructions · photoprism/photoprism B · AGENTS.md · photoprism/photoprism

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	14	5	0%
Commands	0	24	3	0%
Section tags	1	8	2	9%

What each file covers

Sections

0 shared · 14 only in A · 5 only in B

− Instructions for GitHub Copilot
− Purpose
− Single Sources of Truth (SOT)
− Build & Run (local dev; use Makefile first)
− Tests & Lint
− Project Structure & Languages
− Code Review Instructions (for Copilot)
− Style & Patterns
− Commits & Pull Requests
− Performance & Reliability
− When Unsure
− References To Help Copilot Answer Questions
− Output Expectations
− Safety Checklist Before Proposing a CLI Command
+ Migration Package Guidelines
+ Editing Migrations
+ Generation & Verification
+ Test Fixtures
+ Runtime Model

Commands

0 shared · 24 only in A · 3 only in B

− make help
− make list
− make docker-build
− docker compose up
− docker compose logs -f --tail=100 photoprism
− make dep
− make build-js
− make build-go
− make watch-js
− make test
− make test-js
− make vitest-watch
− make vitest-coverage
− make test-go
− make test-short
− go test ./internal/<pkg> -run '<TestName>' -count=1
− make fmt-go
− make lint-go
− make fmt-js
− make lint-js
− make fmt-go swag-fmt swag
− go.mod
− go.sum
− make notice
+ go generate ./internal/entity/migrate
+ go fmt ./internal/entity/migrate
+ go test ./internal/entity/migrate -count=1

Section tags

1 shared · 8 only in A · 2 only in B

− build
− lint-format
− code-style
− architecture
− git-pr
− performance
− do-not
− agent-behaviour
+ testing-strategy
+ database
test

Line diff

+23 added−100 removed11 unchanged9.9% identical

photoprism/photoprism · .github/copilot-instructions.md

@@ −1 @@

1# Instructions for GitHub Copilot

3**Last Updated:** July 28, 2026

5## Purpose

7- Provide Copilot with the single sources of truth for building, testing, and contributing to PhotoPrism.

8- Improve PR reviews and code suggestions by aligning them with our documented workflows and style.

9- Path-specific rules that apply on top of this file live in `.github/instructions/*.instructions.md`.

11## Single Sources of Truth (SOT)

13- Makefile targets (always prefer existing targets): https://github.com/photoprism/photoprism/blob/develop/Makefile

14- Developer Guide – Setup: https://docs.photoprism.app/developer-guide/setup/

15- Developer Guide – Tests: https://docs.photoprism.app/developer-guide/tests/

16- Contributing: https://github.com/photoprism/photoprism/blob/develop/CONTRIBUTING.md

17- Security: https://github.com/photoprism/photoprism/blob/develop/SECURITY.md

18- REST API (Swagger): https://docs.photoprism.dev/

19- REST API Guide: https://docs.photoprism.app/developer-guide/api/

20- Agents reference for tools/commands: https://github.com/photoprism/photoprism/blob/develop/AGENTS.md

21- Code maps: https://github.com/photoprism/photoprism/blob/develop/CODEMAP.md (backend) and https://github.com/photoprism/photoprism/blob/develop/frontend/CODEMAP.md (frontend)

22- Terminology: https://github.com/photoprism/photoprism/blob/develop/GLOSSARY.md

24## Build & Run (local dev; use Makefile first)

26- Show common tasks: `make help` (`make list` shows all targets)

27- Build local image: `make docker-build`

28- Start dev env: `docker compose up` (add `-d` for detached, or run `make up`)

29- Logs: `docker compose logs -f --tail=100 photoprism`

30- Open app: http://localhost:2342/ (HTTP) / https://app.localssl.dev/ (TLS via Traefik when enabled)

31- From the dev container:

32 - Install deps: `make dep`

33 - Build frontend: `make build-js` (or `cd frontend && npm run build`)

34 - Build backend: `make build-go`

35 - Watch frontend: `make watch-js` (stop with Ctrl+C)

36 - Run server binary: `./photoprism start`

38## Tests & Lint

40- Full tests: `make test`

41- Frontend tests (Vitest): `make test-js` (watch: `make vitest-watch`, coverage: `make vitest-coverage`)

42- Backend tests: `make test-go` (slow); `make test-short` for a fast parallel run

43- Targeted Go tests: `go test ./internal/<pkg> -run '<TestName>' -count=1`

44- Formatting and linting:

45 - Go: `make fmt-go` (gofmt + goimports) and `make lint-go` (golangci-lint)

46 - JS/Vue: `make fmt-js` and `make lint-js`. ESLint owns JS and Vue; Prettier owns CSS/SCSS/SASS only. ESLint does not run Prettier, so do not propose reflowing JS to satisfy Prettier.

47- Swagger: after changing API handlers or annotations, run `make fmt-go swag-fmt swag`; never edit `internal/api/swagger.json` by hand.

48- Dependencies: when `go.mod`, `go.sum`, or `package-lock.json` change, regenerate the license reports with `make notice`; never edit `NOTICE` or `frontend/NOTICE` manually.

50## Project Structure & Languages

52- Backend: Go (`internal/`, `pkg/`, `cmd/`) + MariaDB/SQLite

53- Frontend: Vue 3 + Vuetify 3 (`frontend/`)

54- Docker/compose for dev/CI; Traefik used for local TLS in dev profile when enabled.

55- A maintainer's working copy may contain private subdirectories (`plus/`, `pro/`, `portal/`, `specs/`) that are not part of this repository. Never reference their paths from public artifacts such as pull request descriptions, issue comments, or code comments — external readers only see a broken link.

57## Code Review Instructions (for Copilot)

59- 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.

60- Prefer minimal, surgical diffs. Propose changes as concrete patches and reference the relevant Makefile target or doc section.

61- 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.

62- Security: never suggest committing secrets; prefer env vars and `.env` in dev only. Point to SECURITY.md for disclosures.

63- 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.

64- Database/schema: if a change touches persistence, check for migrations and mention `photoprism migrate` / `migrations` commands.

65- API changes: align with the REST API docs/spec; include curl examples only if they match current endpoints and auth notes.

66- UX/i18n: keep UI strings concise, translatable, and consistent; avoid hard-coded language constructs; prefer existing patterns/components.

68## Style & Patterns

70- Go: idiomatic Go, clear error handling, small functions, packages with focused responsibilities. Keep the public surface minimal.

71 - Every added function, including unexported helpers and helpers extracted by a refactor, needs focused coverage in a sibling `*_test.go`.

72 - Code in `pkg/*` must not import from `internal/*`; new code that needs config, entity, or DB access belongs under `internal/`.

73 - Use the permission constants in `pkg/fs` (`fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`) instead of literal file modes.

74 - Doc comments start with the name and stay compact — one line for the "what", plus a line or two only when the "why" cannot be inferred from the code. No issue numbers or change history in comments.

75- Vue/JS: Options API only. Do not introduce TypeScript (no `.ts` files, no `<script lang="ts">`), Composition API, or `<script setup>`.

76 - Shared state lives in reactive singleton modules under `src/common/` and `src/app/`. Do not propose Vuex or Pinia.

77 - Every user-visible string must go through `$gettext`, so it reaches `frontend/src/locales/translations.pot`. Standardized technical identifiers (`Client ID`, `OIDC`, `UUID`) stay literal.

78 - Prefer existing components and model methods over raw `$api` calls in components.

79- Config & flags: suggest `photoprism --help`, `photoprism show config-options` or `photoprism show config-yaml` to verify names before using them.

81## Commits & Pull Requests

83- Commit subjects use the imperative mood with a one-word scope prefix, for example `Config: Add tests for "darktable-cli" path detection`, and must not exceed 80 characters.

84- Reference related issue or PR IDs in the message when applicable, for example `Docker: Use two stage build to reduce image size #123 #5632`.

85- Do not add AI-authorship trailers such as `Co-Authored-By: Copilot` — this repository uses no commit trailers.

86- Issue titles follow the same prefix style; descriptions open with a bold user story (`**As a <role>, I want <goal>, so that <outcome>.**`) and close with a checklist of acceptance criteria using MUST, SHOULD, or MAY.

87- Commit messages, code comments, and public issue or PR text must not describe exploitable details of a security fix; present such changes as general hardening.

89## Performance & Reliability

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

93## When Unsure

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

97## References To Help Copilot Answer Questions

99- Show supported formats/filters: run `photoprism show file-formats` and `photoprism show search-filters` (use results rather than guessing).

100- For CI/dev containers, assume a Linux/Unix shell on amd64 or arm64 by default; for Windows specifics, link https://docs.photoprism.app/developer-guide/faq/

101

102## Output Expectations

103

104- Prefer short, actionable comments with code blocks that pass tests locally: `make test-js` (frontend) / `make test-go` (backend)

105- If a suggestion requires additional context (e.g., DB access, external service), call it out explicitly.

106

107## Safety Checklist Before Proposing a CLI Command

108

109- Include a dry-run or non-destructive variant if possible.

110- Recommend creating/using backups before any reset/migrate.

111

photoprism/photoprism · internal/entity/migrate/AGENTS.md

@@ +1 @@

1# Migration Package Guidelines

3**Last Updated:** June 1, 2026

5This file applies to `internal/entity/migrate/`. Read [`README.md`](README.md) here for the runtime flow, retry behavior, and CLI troubleshooting commands.

7## Editing Migrations

9- Add or change SQL in [`mysql/`](mysql/) and [`sqlite3/`](sqlite3/); do not hand-edit the generated [`dialect_mysql.go`](dialect_mysql.go) or [`dialect_sqlite3.go`](dialect_sqlite3.go) files.

10- Reuse the same timestamp-based migration ID across dialects for the same logical change.

11- Use `.pre.sql` only when the SQL must run before GORM `AutoMigrate(...)`, typically for renames or shape changes that the ORM must see afterward.

12- Keep migrations idempotent when possible with `IF EXISTS`, `IF NOT EXISTS`, or safe update conditions. Failed migrations are recorded once and then skipped on normal startup, so noisy or brittle SQL creates persistent operator friction until someone retries it manually.

13- When (re-)creating a prefix index on a `VARBINARY` column, keep the prefix at **≤ 767 bytes** (the convention is `512`). InnoDB caps key prefixes at 767 bytes on `COMPACT`/`REDUNDANT` row formats, and `VARBINARY` prefixes are counted in bytes, so a longer prefix fails on older or non-`DYNAMIC` installs. See [`README.md`](README.md) → "Index Prefix Limits".

14- If a migration requires custom Go logic instead of plain SQL, keep the reason narrow and obvious. Package-local helpers should still preserve the same retry semantics described in [`README.md`](README.md).

16## Generation & Verification

18- After changing migration SQL, run `go generate ./internal/entity/migrate`.

19- After Go edits in this package, run `go fmt ./internal/entity/migrate`.

20- Verify the package with `go test ./internal/entity/migrate -count=1`.

21- When a change affects operator workflows, also verify the CLI help and status paths with `./photoprism migrations --help`, `./photoprism migrations ls --help`, and `./photoprism migrations run --help`.

23## Test Fixtures

25- Keep [`testdata/migrate_sqlite3`](testdata/migrate_sqlite3) and [`testdata/migrate_mysql.sql`](testdata/migrate_mysql.sql) aligned with the pre-migration schema shape expected by the regression tests.

26- `TestDialectSQLite3` runs against a copied SQLite fixture. `TestDialectMysql` expects a MariaDB service reachable as `mariadb:${MARIADB_PORT:-4001}` with the `migrate` database and user from [`testdata/migrate_mysql.sql`](testdata/migrate_mysql.sql).

28## Runtime Model

30- The `versions` table gates the once-per-release schema initialization path.

31- The `migrations` table stores per-migration `started_at`, `finished_at`, and `error` state.

32- Normal startup does not rerun rows that already failed. Retrying failed rows requires `photoprism migrations run --failed` or explicitly naming migration IDs.

33- Unfinished rows without an error are treated as stale and repeatable only after 60 minutes. More recent unfinished rows are assumed to still be running.

@@ −1 +1 @@

1−# Instructions for GitHub Copilot

1+# Migration Package Guidelines

3−**Last Updated:** July 28, 2026

3+**Last Updated:** June 1, 2026

5−## Purpose

5+This file applies to `internal/entity/migrate/`. Read [`README.md`](README.md) here for the runtime flow, retry behavior, and CLI troubleshooting commands.

7−- Provide Copilot with the single sources of truth for building, testing, and contributing to PhotoPrism.

8−- Improve PR reviews and code suggestions by aligning them with our documented workflows and style.

9−- Path-specific rules that apply on top of this file live in `.github/instructions/*.instructions.md`.

7+## Editing Migrations

108

11−## Single Sources of Truth (SOT)

9+- Add or change SQL in [`mysql/`](mysql/) and [`sqlite3/`](sqlite3/); do not hand-edit the generated [`dialect_mysql.go`](dialect_mysql.go) or [`dialect_sqlite3.go`](dialect_sqlite3.go) files.

10+- Reuse the same timestamp-based migration ID across dialects for the same logical change.

11+- Use `.pre.sql` only when the SQL must run before GORM `AutoMigrate(...)`, typically for renames or shape changes that the ORM must see afterward.

12+- Keep migrations idempotent when possible with `IF EXISTS`, `IF NOT EXISTS`, or safe update conditions. Failed migrations are recorded once and then skipped on normal startup, so noisy or brittle SQL creates persistent operator friction until someone retries it manually.

13+- When (re-)creating a prefix index on a `VARBINARY` column, keep the prefix at **≤ 767 bytes** (the convention is `512`). InnoDB caps key prefixes at 767 bytes on `COMPACT`/`REDUNDANT` row formats, and `VARBINARY` prefixes are counted in bytes, so a longer prefix fails on older or non-`DYNAMIC` installs. See [`README.md`](README.md) → "Index Prefix Limits".

14+- If a migration requires custom Go logic instead of plain SQL, keep the reason narrow and obvious. Package-local helpers should still preserve the same retry semantics described in [`README.md`](README.md).

1215

13−- Makefile targets (always prefer existing targets): https://github.com/photoprism/photoprism/blob/develop/Makefile

14−- Developer Guide – Setup: https://docs.photoprism.app/developer-guide/setup/

15−- Developer Guide – Tests: https://docs.photoprism.app/developer-guide/tests/

16−- Contributing: https://github.com/photoprism/photoprism/blob/develop/CONTRIBUTING.md

17−- Security: https://github.com/photoprism/photoprism/blob/develop/SECURITY.md

18−- REST API (Swagger): https://docs.photoprism.dev/

19−- REST API Guide: https://docs.photoprism.app/developer-guide/api/

20−- Agents reference for tools/commands: https://github.com/photoprism/photoprism/blob/develop/AGENTS.md

21−- Code maps: https://github.com/photoprism/photoprism/blob/develop/CODEMAP.md (backend) and https://github.com/photoprism/photoprism/blob/develop/frontend/CODEMAP.md (frontend)

22−- Terminology: https://github.com/photoprism/photoprism/blob/develop/GLOSSARY.md

16+## Generation & Verification

2317

24−## Build & Run (local dev; use Makefile first)

18+- After changing migration SQL, run `go generate ./internal/entity/migrate`.

19+- After Go edits in this package, run `go fmt ./internal/entity/migrate`.

20+- Verify the package with `go test ./internal/entity/migrate -count=1`.

21+- When a change affects operator workflows, also verify the CLI help and status paths with `./photoprism migrations --help`, `./photoprism migrations ls --help`, and `./photoprism migrations run --help`.

2522

26−- Show common tasks: `make help` (`make list` shows all targets)

27−- Build local image: `make docker-build`

28−- Start dev env: `docker compose up` (add `-d` for detached, or run `make up`)

29−- Logs: `docker compose logs -f --tail=100 photoprism`

30−- Open app: http://localhost:2342/ (HTTP) / https://app.localssl.dev/ (TLS via Traefik when enabled)

31−- From the dev container:

32− - Install deps: `make dep`

33− - Build frontend: `make build-js` (or `cd frontend && npm run build`)

34− - Build backend: `make build-go`

35− - Watch frontend: `make watch-js` (stop with Ctrl+C)

36− - Run server binary: `./photoprism start`

23+## Test Fixtures

3724

38−## Tests & Lint

25+- Keep [`testdata/migrate_sqlite3`](testdata/migrate_sqlite3) and [`testdata/migrate_mysql.sql`](testdata/migrate_mysql.sql) aligned with the pre-migration schema shape expected by the regression tests.

26+- `TestDialectSQLite3` runs against a copied SQLite fixture. `TestDialectMysql` expects a MariaDB service reachable as `mariadb:${MARIADB_PORT:-4001}` with the `migrate` database and user from [`testdata/migrate_mysql.sql`](testdata/migrate_mysql.sql).

3927

40−- Full tests: `make test`

41−- Frontend tests (Vitest): `make test-js` (watch: `make vitest-watch`, coverage: `make vitest-coverage`)

42−- Backend tests: `make test-go` (slow); `make test-short` for a fast parallel run

43−- Targeted Go tests: `go test ./internal/<pkg> -run '<TestName>' -count=1`

44−- Formatting and linting:

45− - Go: `make fmt-go` (gofmt + goimports) and `make lint-go` (golangci-lint)

46− - JS/Vue: `make fmt-js` and `make lint-js`. ESLint owns JS and Vue; Prettier owns CSS/SCSS/SASS only. ESLint does not run Prettier, so do not propose reflowing JS to satisfy Prettier.

47−- Swagger: after changing API handlers or annotations, run `make fmt-go swag-fmt swag`; never edit `internal/api/swagger.json` by hand.

48−- Dependencies: when `go.mod`, `go.sum`, or `package-lock.json` change, regenerate the license reports with `make notice`; never edit `NOTICE` or `frontend/NOTICE` manually.

28+## Runtime Model

4929

50−## Project Structure & Languages

51−

52−- Backend: Go (`internal/`, `pkg/`, `cmd/`) + MariaDB/SQLite

53−- Frontend: Vue 3 + Vuetify 3 (`frontend/`)

54−- Docker/compose for dev/CI; Traefik used for local TLS in dev profile when enabled.

55−- A maintainer's working copy may contain private subdirectories (`plus/`, `pro/`, `portal/`, `specs/`) that are not part of this repository. Never reference their paths from public artifacts such as pull request descriptions, issue comments, or code comments — external readers only see a broken link.

56−

57−## Code Review Instructions (for Copilot)

58−

59−- 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.

60−- Prefer minimal, surgical diffs. Propose changes as concrete patches and reference the relevant Makefile target or doc section.

61−- 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.

62−- Security: never suggest committing secrets; prefer env vars and `.env` in dev only. Point to SECURITY.md for disclosures.

63−- 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.

64−- Database/schema: if a change touches persistence, check for migrations and mention `photoprism migrate` / `migrations` commands.

65−- API changes: align with the REST API docs/spec; include curl examples only if they match current endpoints and auth notes.

66−- UX/i18n: keep UI strings concise, translatable, and consistent; avoid hard-coded language constructs; prefer existing patterns/components.

67−

68−## Style & Patterns

69−

70−- Go: idiomatic Go, clear error handling, small functions, packages with focused responsibilities. Keep the public surface minimal.

71− - Every added function, including unexported helpers and helpers extracted by a refactor, needs focused coverage in a sibling `*_test.go`.

72− - Code in `pkg/*` must not import from `internal/*`; new code that needs config, entity, or DB access belongs under `internal/`.

73− - Use the permission constants in `pkg/fs` (`fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`) instead of literal file modes.

74− - Doc comments start with the name and stay compact — one line for the "what", plus a line or two only when the "why" cannot be inferred from the code. No issue numbers or change history in comments.

75−- Vue/JS: Options API only. Do not introduce TypeScript (no `.ts` files, no `<script lang="ts">`), Composition API, or `<script setup>`.

76− - Shared state lives in reactive singleton modules under `src/common/` and `src/app/`. Do not propose Vuex or Pinia.

77− - Every user-visible string must go through `$gettext`, so it reaches `frontend/src/locales/translations.pot`. Standardized technical identifiers (`Client ID`, `OIDC`, `UUID`) stay literal.

78− - Prefer existing components and model methods over raw `$api` calls in components.

79−- Config & flags: suggest `photoprism --help`, `photoprism show config-options` or `photoprism show config-yaml` to verify names before using them.

80−

81−## Commits & Pull Requests

82−

83−- Commit subjects use the imperative mood with a one-word scope prefix, for example `Config: Add tests for "darktable-cli" path detection`, and must not exceed 80 characters.

84−- Reference related issue or PR IDs in the message when applicable, for example `Docker: Use two stage build to reduce image size #123 #5632`.

85−- Do not add AI-authorship trailers such as `Co-Authored-By: Copilot` — this repository uses no commit trailers.

86−- Issue titles follow the same prefix style; descriptions open with a bold user story (`**As a <role>, I want <goal>, so that <outcome>.**`) and close with a checklist of acceptance criteria using MUST, SHOULD, or MAY.

87−- Commit messages, code comments, and public issue or PR text must not describe exploitable details of a security fix; present such changes as general hardening.

88−

89−## Performance & Reliability

90−

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

92−

93−## When Unsure

94−

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

96−

97−## References To Help Copilot Answer Questions

98−

99−- Show supported formats/filters: run `photoprism show file-formats` and `photoprism show search-filters` (use results rather than guessing).

100−- For CI/dev containers, assume a Linux/Unix shell on amd64 or arm64 by default; for Windows specifics, link https://docs.photoprism.app/developer-guide/faq/

101−

102−## Output Expectations

103−

104−- Prefer short, actionable comments with code blocks that pass tests locally: `make test-js` (frontend) / `make test-go` (backend)

105−- If a suggestion requires additional context (e.g., DB access, external service), call it out explicitly.

106−

107−## Safety Checklist Before Proposing a CLI Command

108−

109−- Include a dry-run or non-destructive variant if possible.

110−- Recommend creating/using backups before any reset/migrate.

30+- The `versions` table gates the once-per-release schema initialization path.

31+- The `migrations` table stores per-migration `started_at`, `finished_at`, and `error` state.

32+- Normal startup does not rerun rows that already failed. Retrying failed rows requires `photoprism migrations run --failed` or explicitly naming migration IDs.

33+- Unfinished rows without an error are treated as stale and repeatable only after 60 minutes. More recent unfinished rows are assumed to still be running.

11134