From 7e419f7419da74dfaffccad5e92c26bb19d0e7a8 Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Thu, 25 Sep 2025 20:08:45 +0200 Subject: [PATCH] Docs: Add "Last Updated" timestamps to AGENTS.md and CODEMAP.md files Signed-off-by: Michael Mayer --- AGENTS.md | 3 +++ CODEMAP.md | 2 ++ 2 files changed, 5 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8da397197..6e9dffd04 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # PhotoPrism® Repository Guidelines +**Last Updated:** September 25, 2025 + ## Purpose This file tells automated coding agents (and humans) where to find the single sources of truth for building, testing, and contributing to PhotoPrism. @@ -261,6 +263,7 @@ If anything in this file conflicts with the `Makefile` or the Developer Guide, t - Respect precedence: `options.yml` overrides CLI/env values, which override defaults. When adding a new option, update `internal/config/options.go` (yaml/flag tags), register it in `internal/config/flags.go`, expose a getter, surface it in `*config.Report()`, and write generated values back to `options.yml` by setting `c.options.OptionsYaml` before persisting. Use `CliTestContext` in `internal/config/test.go` to exercise new flags. - When touching configuration in Go code, use the public accessors on `*config.Config` (e.g. `Config.JWKSUrl()`, `Config.SetJWKSUrl()`, `Config.ClusterUUID()`) instead of mutating `Config.Options()` directly; reserve raw option tweaks for test fixtures only. - Logging: use the shared logger (`event.Log`) via the package-level `log` variable (see `internal/auth/jwt/logger.go`) instead of direct `fmt.Print*` or ad-hoc loggers. +- Cluster registry tests (`internal/service/cluster/registry`) currently rely on a full test config because they persist `entity.Client` rows. They run migrations and seed the SQLite DB, so they are intentionally slow. If you refactor them, consider sharing a single `config.TestConfig()` across subtests or building a lightweight schema harness; do not swap to the minimal config helper unless the tests stop touching the database. - Favor explicit CLI flags: check `c.cliCtx.IsSet("")` before overriding user-supplied values, and follow the `ClusterUUID` pattern (`options.yml` → CLI/env → generated UUIDv4 persisted). - Database helpers: reuse `conf.Db()` / `conf.Database*()`, avoid GORM `WithContext`, quote MySQL identifiers, and reject unsupported drivers early. - Handler conventions: reuse limiter stacks (`limiter.Auth`, `limiter.Login`) and `limiter.AbortJSON` for 429s, lean on `api.ClientIP`, `header.BearerToken`, and `Abort*` helpers, compare secrets with constant time checks, set `Cache-Control: no-store` on sensitive responses, and register routes in `internal/server/routes.go`. For new list endpoints default `count=100` (max 1000) and `offset≥0`, document parameters explicitly, and set portal mode via `PHOTOPRISM_NODE_ROLE=portal` plus `PHOTOPRISM_JOIN_TOKEN` when needed. diff --git a/CODEMAP.md b/CODEMAP.md index a3dbad2ee..8dee9d0b9 100644 --- a/CODEMAP.md +++ b/CODEMAP.md @@ -1,5 +1,7 @@ PhotoPrism — Backend CODEMAP +**Last Updated:** September 24, 2025 + Purpose - Give agents and contributors a fast, reliable map of where things live and how they fit together, so you can add features, fix bugs, and write tests without spelunking. - Sources of truth: prefer Makefile targets and the Developer Guide linked in AGENTS.md.