From c85e694c1d6e5e68425670294a37c9e5ad8cad05 Mon Sep 17 00:00:00 2001
From: Will Miao <13051207myq@gmail.com>
Date: Thu, 25 Sep 2025 08:36:15 +0800
Subject: [PATCH] docs: update repository guidelines for clarity and
consistency
---
AGENTS.md | 17 ++++++++++-------
1 file changed, 10 insertions(+), 7 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 740491c5..31a731cc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,19 +1,22 @@
-# Repository Guidelines
+# Repository Guidelines
## Project Structure & Module Organization
-ComfyUI LoRA Manager pairs a Python backend with lightweight browser scripts. Backend modules live in `py/`, organized by responsibility: HTTP entry points under `routes/`, feature logic in `services/`, reusable helpers within `utils/`, and custom nodes in `nodes/`. Front-end widgets that extend the ComfyUI interface sit in `web/comfyui/`, while static images and templates are in `static/` and `templates/`. Shared localization files are stored in `locales/`, with workflow examples under `example_workflows/`. Tests currently reside alongside the source (`test_i18n.py`) until a dedicated `tests/` folder is introduced.
+ComfyUI LoRA Manager pairs a Python backend with browser-side widgets. Backend modules live in py/ with HTTP entry points in py/routes/, feature logic in py/services/, shared helpers in py/utils/, and custom nodes in py/nodes/. UI scripts extend ComfyUI from web/comfyui/, while deploy-ready assets remain in static/ and templates/. Localization files live in locales/, example workflows in example_workflows/, and interim tests such as test_i18n.py sit beside their source until a dedicated tests/ tree lands.
## Build, Test, and Development Commands
-Install dependencies with `pip install -r requirements.txt` from the repo root. Launch the standalone server for iterative work via `python standalone.py --port 8188`; ComfyUI users can also load the extension directly through ComfyUI's custom node manager. Run backend checks with `python -m pytest test_i18n.py`, and target new test files explicitly (e.g. `python -m pytest tests/test_recipes.py` once added). Use `python scripts/sync_translation_keys.py` to reconcile locale keys after updating UI strings.
+- pip install -r requirements.txt installs backend dependencies.
+- python standalone.py --port 8188 launches the standalone server for iterative development.
+- python -m pytest test_i18n.py runs the current regression suite; target new files explicitly, e.g. python -m pytest tests/test_recipes.py.
+- python scripts/sync_translation_keys.py synchronizes locale keys after UI string updates.
## Coding Style & Naming Conventions
-Follow PEP 8 with four-space indentation and descriptive snake_case module/function names, mirroring files such as `py/services/settings_manager.py`. Classes remain PascalCase, constants UPPER_SNAKE_CASE, and loggers retrieved via `logging.getLogger(__name__)`. Prefer explicit type hints for new public APIs and docstrings that clarify side effects. JavaScript in `web/comfyui/` is modern ES modules; keep imports relative, favor camelCase functions, and mirror existing file suffixes like `_widget.js` for UI components.
+Follow PEP 8 with four-space indentation and descriptive snake_case file and function names such as settings_manager.py. Classes stay PascalCase, constants in UPPER_SNAKE_CASE, and loggers retrieved via logging.getLogger(__name__). Prefer explicit type hints and docstrings on public APIs. JavaScript under web/comfyui/ uses ES modules with camelCase helpers and the _widget.js suffix for UI components.
## Testing Guidelines
-Extend pytest coverage by co-locating tests near the code under test or in `tests/` with names like `test_.py`. When introducing new routes or services, add regression cases that mock ComfyUI dependencies (see the standalone mocking helpers in `standalone.py`). Prioritize deterministic fixtures for filesystem interactions and ensure translations include coverage when adding new locale keys. Always run `python -m pytest` before submitting work.
+Pytest powers backend tests. Name modules test_.py and keep them near the code or in a future tests/ package. Mock ComfyUI dependencies through helpers in standalone.py, keep filesystem fixtures deterministic, and ensure translations are covered. Run python -m pytest before submitting changes.
## Commit & Pull Request Guidelines
-Commits follow the conventional pattern seen in `git log` (`feat(scope):`, `fix(scope):`, `chore(scope):`). Keep messages imperative and scoped to a single change. Pull requests should summarize the problem, detail the solution, list manual test evidence, and link any GitHub issues. Include UI screenshots or GIFs when front-end behavior changes, and call out migration steps (e.g., settings updates) in the PR description.
+Commits follow the conventional format, e.g. feat(settings): add default model path, and should stay focused on a single concern. Pull requests must outline the problem, summarize the solution, list manual verification steps (server run, targeted pytest), and link related issues. Include screenshots or GIFs for UI or locale updates and call out migration steps such as settings.json adjustments.
## Configuration & Localization Tips
-Sample configuration defaults live in `settings.json.example`; copy it to `settings.json` and adjust model directories before running the standalone server. Whenever you add UI text, update `locales/.json` and run the translation sync script. Store reference assets in `civitai/` or `docs/` rather than mixing them with production templates, keeping the runtime folders (`static/`, `templates/`) deploy-ready.
+Copy settings.json.example to settings.json and adapt model directories before running the standalone server. Store reference assets in civitai/ or docs/ to keep runtime directories deploy-ready. Whenever UI text changes, update every locales/<lang>.json file and rerun the translation sync script so ComfyUI surfaces localized strings.