mirror of
https://github.com/photoprism/photoprism.git
synced 2026-07-17 16:49:04 +00:00
Rules: Refine and dedupe agent rules, fix stale Vuex claim
This commit is contained in:
Michael Mayer
parent
bbc5d8715b
commit
29a994a648
6 changed files with 44 additions and 40 deletions
|
|
@ -50,20 +50,9 @@ go test ./internal/entity/... -count=1 -tags="slow,develop"
|
|||
|
||||
## Formatting & Linting
|
||||
|
||||
- `make fmt` — format everything (Go + JS + Swagger)
|
||||
- `make fmt-go` — runs `go fmt`, `gofmt -w -s`, then `goimports -w -local "github.com/photoprism"` on `pkg/`, `internal/`, `cmd/`
|
||||
- `make fmt-js` — runs ESLint + Prettier via `npm run fmt` in `frontend/`
|
||||
- `make fmt-swag` / `make swag` — format and regenerate Swagger docs (`internal/api/swagger.json`)
|
||||
- `make lint-go` — runs golangci-lint (prints findings without failing due to `--issues-exit-code 0`)
|
||||
- `make lint-js` — runs ESLint/Prettier for frontend
|
||||
Available targets: `make fmt` (everything), `make fmt-go`, `make fmt-js`, `make fmt-swag` / `make swag` (Swagger), `make lint-go`, `make lint-js`. Detailed conventions live in `.claude/rules/go-code-style.md` and `.claude/rules/frontend-rules.md`.
|
||||
|
||||
Always run `make fmt-go` before committing Go changes and `make fmt-js` before committing frontend changes.
|
||||
When creating or editing shell scripts, run `shellcheck <file>` and resolve warnings.
|
||||
|
||||
When editing or creating Markdown files that contain tables, format them with:
|
||||
```bash
|
||||
npx --yes markdown-table-formatter <filename>
|
||||
```
|
||||
When creating or editing shell scripts, run `shellcheck <file>` and resolve warnings. When editing Markdown files that contain tables, format them with `npx --yes markdown-table-formatter <filename>`.
|
||||
|
||||
## Schema Migrations
|
||||
|
||||
|
|
@ -114,19 +103,17 @@ PhotoPrism is a self-hosted photo management app. The backend is Go, the fronten
|
|||
|
||||
Vue 3 app using the Options API and Vuetify 3.
|
||||
|
||||
| Directory | Purpose |
|
||||
|---------------------------|-----------------------------------------------------------------------------|
|
||||
| `frontend/src/model/` | Client-side models mirroring API responses (Photo, Album, File, User, etc.) |
|
||||
| `frontend/src/app/` | App bootstrap, Vuex store, routing |
|
||||
| `frontend/src/page/` | Page-level components |
|
||||
| `frontend/src/component/` | Reusable UI components |
|
||||
| `frontend/src/common/` | Shared utilities and API client |
|
||||
| `frontend/src/locales/` | i18n translation files |
|
||||
| `frontend/tests/` | Vitest unit tests + TestCafe acceptance tests |
|
||||
| Directory | Purpose |
|
||||
|---------------------------|-------------------------------------------------------------------------------------------------|
|
||||
| `frontend/src/model/` | Client-side models mirroring API responses (Photo, Album, File, User, etc.) |
|
||||
| `frontend/src/app/` | App bootstrap, routing (`routes.js`), and the `$session` reactive singleton |
|
||||
| `frontend/src/page/` | Page-level components |
|
||||
| `frontend/src/component/` | Reusable UI components |
|
||||
| `frontend/src/common/` | Shared utilities, the API client (`$api`), and reactive singletons (`$config`, `$view`, `$log`) |
|
||||
| `frontend/src/locales/` | i18n translation files |
|
||||
| `frontend/tests/` | Vitest unit tests + TestCafe acceptance tests |
|
||||
|
||||
- Use the Options API consistently; do not introduce Composition API.
|
||||
- Keep all UI strings translatable; never hardcode locale strings.
|
||||
- Follow existing Vuex store patterns for state management.
|
||||
State management uses reactive singleton modules in `src/common/` and `src/app/`, not Vuex or Pinia. Frontend code-style, formatting, testing, translation, and Playwright rules live in `.claude/rules/frontend-rules.md`.
|
||||
|
||||
### API Conventions
|
||||
|
||||
|
|
@ -145,15 +132,16 @@ Verify config option names before using them:
|
|||
./photoprism show config-yaml
|
||||
```
|
||||
|
||||
### Commit Messages
|
||||
### Verify Before Propagating
|
||||
|
||||
Use concise, imperative subjects with a one-word prefix indicating scope (e.g. `Config: Add tests for "darktable-cli" path detection`). Reference issue/PR IDs when relevant (e.g. `Docker: Use two stage build #123`). Commit messages must not exceed 80 characters.
|
||||
Before promoting a claim from `CLAUDE.md`, `AGENTS.md`, a memory entry, or another spec into a new rule, spec, code comment, or commit message, verify it against the current code (grep imports, list directories, read the cited file). Stale documentation silently turns into stale rules and stale specs that future sessions will trust. When the claim names a package, function, file, or framework, the cost of one grep is much smaller than the cost of repeating an error across multiple files.
|
||||
|
||||
Do not add `Co-Authored-By: Claude …` trailers to commit messages.
|
||||
### Detailed Rules
|
||||
|
||||
### Key Style Notes
|
||||
Topic-specific conventions live under `.claude/rules/` and are loaded alongside this file:
|
||||
|
||||
- **Go**: idiomatic Go, small functions, wrapped errors with context, minimal public surface area. Use `goimports` with `-local "github.com/photoprism"` to group imports. Code in `pkg/*` MUST NOT import from `internal/*`.
|
||||
- **Tests**: use `config.TestConfig()` for shared fixtures or `config.NewMinimalTestConfigWithDb("<name>", t.TempDir())` for isolated test DBs. Use build tags `-tags="slow,develop"` for the full test suite. Do not run multiple test commands in parallel (shared fixtures/DB).
|
||||
- **Destructive CLI commands** (`photoprism reset`, `users reset`, `auth reset`, `audit reset`) require explicit `--yes` and should never be used in examples without backup warnings.
|
||||
- **Safety**: Never commit secrets or local configs. Do not run `git config`. Do not run destructive commands against production data.
|
||||
- `go-code-style.md`, `go-testing.md` — Go style, doc comments, package boundaries, test patterns, fixtures.
|
||||
- `frontend-rules.md` — JS/Vue code style, formatting, dependencies, tests, Playwright, translations.
|
||||
- `commit-and-docs-style.md` — commit-message format, GitHub issue templates, spec heading style.
|
||||
- `safety-and-security.md` — Git/data safety, destructive commands, file I/O and archive-extraction policies, HTTP download helpers.
|
||||
- `api-and-config.md`, `cluster-operations.md`, `import-index-download.md`, `build-and-runtime.md`, `sources-of-truth.md` — domain-specific guidance.
|
||||
|
|
|
|||
|
|
@ -10,6 +10,8 @@ If the commit relates to specific issues or pull requests, reference their IDs i
|
|||
|
||||
Commit messages must not exceed 80 characters in length.
|
||||
|
||||
Do not add `Co-Authored-By: Claude …` trailers (or any other AI-authorship trailer) to commit messages.
|
||||
|
||||
## GitHub Issues
|
||||
|
||||
Issue titles MUST be concise, use the imperative mood, and start with a single capitalized prefix followed by a colon and a space, e.g. `Search: Add filter for RAW image formats`.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,19 @@
|
|||
## Frontend Code Style & Test Coverage
|
||||
|
||||
- **Doc comments are required**, even when a test isn't practical. Every new JS function and every Vue component `methods:` / `computed:` entry needs a brief doc comment above it — including module-internal helpers, not just `export`-ed functions. The house style is a single `// Name does X.` line (see `src/options/themes.js`, `src/common/util.js`); use a `/* … */` block for multi-line notes.
|
||||
- Vue Single-File Components: add a one-line doc comment above the default export and a one-liner above each non-trivial method, computed property, or watcher. Trivial getters (`isOpen: () => this.open`) can skip the comment.
|
||||
- Test new JS functions (including helpers) and new Vue components whenever practical; update existing tests when behavior changes. When a unit test is impractical (DOM-heavy flows, third-party widget integration), the doc comment is still mandatory — it's the minimum bar.
|
||||
- **JavaScript only — do not introduce TypeScript.** The frontend is a pure JS + Vue SFC codebase: no `.ts` files, no `tsconfig.json`, no `<script lang="ts">` blocks. JSDoc type annotations in comments are fine; full TS migrations are out of scope.
|
||||
- Use the Options API in Vue components (consistent with the rest of the codebase); do not introduce Composition API or `<script setup>`.
|
||||
- **State management:** shared state lives in reactive singleton modules under `src/common/` and `src/app/` (e.g., `app/session.js`, `common/config.js`, `common/clipboard.js`, `common/log.js`) that export a `reactive()` / `ref()` object directly; components access them via `import` or via the globally-installed `$config` / `$session` plugins. Do not introduce Vuex, Pinia, or new ad-hoc stores — extend an existing singleton or add a new one alongside its peers in `common/` or `app/`.
|
||||
|
||||
## Frontend Formatting
|
||||
|
||||
- ESLint + Prettier own formatting. After edits run `make fmt-js` (or `npm run fmt` inside `frontend/`) and `make lint-js` to verify; `frontend/eslint.config.mjs` is the flat-config source of truth.
|
||||
- Prettier uses `printWidth: 160`, double quotes, semicolons, `trailingComma: "es5"`, and `proseWrap: "never"` (see `frontend/.prettierrc.json`). Do not hand-wrap long lines — let Prettier decide. CSS/SCSS use `tabWidth: 4`.
|
||||
- The repo-root `.editorconfig` covers indentation and newline style; don't override it locally.
|
||||
- Vue SFC block order is `<template>` → `<script>` → `<style>`; keep it consistent with existing components.
|
||||
|
||||
## Frontend Dependencies & Pins
|
||||
|
||||
- `frontend/README.md` is the canonical doc for pin rationale, the `overrides` layer, ESM-only upgrade blockers, and the orphan-audit pattern — read it before bumping any non-caret pin or adding/removing a top-level dep.
|
||||
|
|
@ -5,10 +21,6 @@
|
|||
- npm is a workspace; run `npm install --ignore-scripts --no-audit --no-fund --no-update-notifier` from the **repo root** (not `frontend/`) so the root `package-lock.json` updates. After dep changes also run `make audit`, `make build-js`, `make test-js`, and `make notice`.
|
||||
- Before adding a new dep or removing one as "unused", run `rg -nF "<pkg>" frontend ...` plus `npm ls <pkg> --all` to confirm there's no transitive consumer or peer-dep. Recent precedents: `postcss-url`, `@vitejs/plugin-react`, `cheerio`, `@testing-library/react`, `vite-tsconfig-paths` (all true orphans removed once consumer left).
|
||||
|
||||
## Frontend Test Coverage
|
||||
|
||||
- Test new JS functions (including helpers) and new Vue components whenever practical; update existing tests when behavior changes.
|
||||
|
||||
## Frontend Linting & Test Entry Points
|
||||
|
||||
- Follow the lint/format scripts in `frontend/package.json`; all added JS, Vue, and tests must conform.
|
||||
|
|
@ -46,6 +58,7 @@
|
|||
|
||||
## Frontend Translations
|
||||
|
||||
- Never hardcode locale strings in templates or scripts — every user-visible string MUST go through `$gettext` / `T` so it appears in `frontend/src/locales/translations.pot`.
|
||||
- Extraction source of truth: root `make gettext-extract` (via `scripts/gettext-extract.sh`), which scans `frontend/src` plus available overlays in `plus/frontend`, `pro/frontend`, `portal/frontend`.
|
||||
- Avoid punctuation-only gettext keys (e.g. `$gettext("—")`) — they clutter `frontend/src/locales/translations.pot`.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
## Go Code Style
|
||||
|
||||
- Run `make lint-go` (golangci-lint) after Go changes; prefer `golangci-lint run ./internal/<pkg>/...` for focused edits.
|
||||
- Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period. All new functions (including unexported helpers) need a concise doc comment explaining behavior.
|
||||
- Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
|
||||
- Every new function, including unexported helpers, needs a concise doc comment that explains its purpose.
|
||||
- For short examples inside comments, indent code rather than using backticks; godoc treats indented blocks as preformatted.
|
||||
- Every Go package must contain a `<package>.go` file in its root (e.g. `internal/auth/jwt/jwt.go`) with the standard license header and a short package description comment.
|
||||
- Go is formatted by `gofmt` with tabs. Do not hand-format indentation. After edits run `make fmt-go` (gofmt + goimports).
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
- If `git status` shows unexpected changes, assume a human might be editing; ask before using reset commands like `git checkout` or `git reset`.
|
||||
- Do not run `git config` (global or repo-level); changing Git configuration is prohibited for agents. Nested subrepos (e.g. `specs/`) may lack a configured committer identity — pass `-c user.email=… -c user.name=…` to the specific `git commit` invocation rather than configuring the repo.
|
||||
- Do not run destructive commands against production data. Prefer ephemeral volumes and test fixtures for acceptance tests.
|
||||
- Do not run destructive commands against production data. Prefer ephemeral volumes and test fixtures for acceptance tests. The destructive CLI commands `photoprism reset`, `users reset`, `auth reset`, and `audit reset` require explicit `--yes`; never invoke them in examples or scripts without a backup warning.
|
||||
- Never commit secrets, local configurations, or cache files. Use environment variables or a local `.env`. Ensure `.env`, `.config`, `.local`, `.codex`, and `.gocache` are in `.gitignore` and `.dockerignore`.
|
||||
- Prefer existing caches, workers, and batching strategies in code and `Makefile`. Consider memory/CPU impact of changes; only suggest benchmarks or profiling when justified.
|
||||
- Regenerate `NOTICE` files with `make notice` when dependencies change (e.g. `go.mod`, `go.sum`, `package-lock.json`). Do not edit `NOTICE` or `frontend/NOTICE` manually.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue