malkuthroandClaude Opus 4.7
ee8ccefdf8
Bundles two changes for v0.1.7: 1. PR #36 (already on main, just rolling [Unreleased] -> [0.1.7]): suffix all node display names with " (Koolook)" so they group together in ComfyUI's node-add search. Class IDs unchanged. 2. Docs reorg: - git mv Glossary.md -> docs/reference/glossary.md - git mv RELEASING.md -> docs/maintainers/releasing.md - Three audience buckets under docs/: user_guide/ (end users), reference/ (lookups), maintainers/ (project ops). Each gets a short index README.md. - Top-level docs/README.md as the navigation entry point. - New: docs/maintainers/registry-api.md captures the Comfy Registry undocumented version-management API (deprecate/yank/status enum, auto-deprecation behavior, curl recipes, optional GH Actions workflow YAML for codified mgmt without exposing the token). - New: docs/maintainers/node-versioning.md codifies the rules from the v0.1.5 PR-review discussion for changing INPUT_TYPES / RETURN_TYPES / class names without breaking saved workflows. - Imported the existing untracked docs/ images that the maintainer started locally (node inventory screenshot, Easy Image Batch helper image). - Cross-references updated in README.md, CLAUDE.md, the issue template, and .claude/skills/add-external-fork/SKILL.md. Root drops from 6 -> 4 markdown files. The four that stay (README, LICENSE, CHANGELOG, CLAUDE.md) are the ones that *must* live there for GitHub / Comfy Registry / tooling / Claude Code reasons. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# Glossary
|
|
|
|
Short, plain-English definitions for this repo workflow.
|
|
|
|
## Root `__init__.py`
|
|
- The ComfyUI entry file for this plugin.
|
|
- Its job is to import node mappings and expose `NODE_CLASS_MAPPINGS` / `NODE_DISPLAY_NAME_MAPPINGS`.
|
|
- Keep it clean and focused on loading nodes.
|
|
|
|
## Main Repo
|
|
- This repository: `ComfyUI-Koolook`.
|
|
- Stores Koolook-owned code, docs, and lightweight integration wrappers.
|
|
- Should not store full external third-party repositories.
|
|
|
|
## External Forks
|
|
- Raw upstream/fork reference repos kept outside MAIN.
|
|
- Default location is a sibling folder: `../ComfyUI-Forks`.
|
|
- Each external repo should be pinned to a version/tag + exact commit.
|
|
|
|
## Wrapper
|
|
- A small adapter module in `forks/` that loads locally tracked modified nodes and namespaces node IDs.
|
|
- Purpose: avoid collisions and keep external logic separate from root loader.
|
|
- For Radiance, the package entrypoint is `forks/radiance_koolook/__init__.py`.
|
|
|
|
## Version Folder
|
|
- A folder under `forks/radiance_koolook/versions/` that stores one maintained codebase snapshot (example: `v1_0_1`).
|
|
- Keep upstream parity metadata in `UPSTREAM_PIN.yaml` inside each version folder.
|
|
|
|
## Namespace Suffix
|
|
- A suffix added to internal node IDs (example: `__koolook_v1_0_1`).
|
|
- Prevents collisions between versions (v1, v2, upstream, etc.).
|
|
- Protects old workflows from breaking.
|
|
|
|
## `forks/forks_manifest.yaml`
|
|
- Machine-readable tracker for external dependencies.
|
|
- Contains source repo, source ref, pinned commit, and external relative path.
|
|
- This is the source of truth for reproducible setup on new machines.
|
|
|
|
## `forks/THIRD_PARTY.md`
|
|
- Human-readable attribution and notes.
|
|
- Explains what was modified and why.
|
|
|
|
## Portable Paths
|
|
- Prefer relative paths so setup works on Windows/macOS/Linux.
|
|
- Keep external references under `../ComfyUI-Forks` for portable machine setup.
|
|
|
|
## Pinned Commit
|
|
- The exact git commit hash you lock to for reproducibility.
|
|
- Use this when moving to another computer so behavior matches exactly.
|
|
|
|
## Sibling Project
|
|
- A related repository or folder that lives **outside MAIN** and is consulted (read-only) but never imported by MAIN at runtime.
|
|
- Examples: external forks root, ComfyUI knowledge database, personal knowledge database.
|
|
- Always referenced by env var (e.g. `KOLOOK_COMFYUI_KB_DIR`) — never by absolute path in committed files.
|
|
- Real paths live in `.env` (gitignored). The committed `.env.example` declares the variable names.
|
|
- Treated as runtime-optional: if the env var is unset and there is no portable default, the sibling is considered unavailable.
|
|
|
|
## `.env` / `.env.example`
|
|
- `.env.example` (committed) — public template listing the env var names with safe placeholder values.
|
|
- `.env` (gitignored) — each user's local file with real machine-specific paths.
|
|
- Pattern matches the existing `KOLOOK_FORKS_DIR` convention.
|