nodes/malkuthro-ComfyUI-Koolook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
d763b36adc652b95e1f677ce5ae500206ea5108d
malkuthro-ComfyUI-Koolook/docs/reference/glossary.md
T
malkuthroandClaude Opus 4.7 ee8ccefdf8 docs(reorg) + chore: roll [Unreleased] forward + bump 0.1.7 (#37) 
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>
2026-05-03 23:26:46 +02:00

2.8 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink