malkuthro-ComfyUI-Koolook/forks/README.md

Forks Workflow

This folder is the single source for all fork tracking metadata inside MAIN.

Purpose

• Keep modified forked code in MAIN under versioned paths (for GitHub tracking).
• Keep raw external checkouts outside MAIN under ../ComfyUI-Forks (for upstream reference/sync).
• Keep all fork metadata in one place:
  • forks/forks_manifest.yaml
  • forks/THIRD_PARTY.md

Folder Layout in MAIN

• forks/radiance_koolook/__init__.py -> package entrypoint used by root __init__.py
• forks/radiance_koolook/versions/v1_0_1/ -> local modified node sources
• forks/radiance_koolook/versions/<version>/UPSTREAM_PIN.yaml -> exact upstream parity pin

External Folder Naming (outside MAIN)

Root: ../ComfyUI-Forks

• Pinned baseline checkout:
  • radiance-v1.0.1-koolook
• Rolling upstream checkout:
  • radiance-main-upstream

These names are referenced from forks/forks_manifest.yaml.

Referencing System

For each fork entry in forks/forks_manifest.yaml:

• source_repo = canonical upstream URL
• source_ref = release/tag (or baseline descriptor)
• pinned_commit = exact reproducible commit hash
• external_checkout.relative_path_from_forks_root = pinned raw reference folder
• external_checkout.upstream_tracking_path_from_forks_root = rolling upstream folder
• local_paths = files tracked in MAIN

Tagging Policy (from now on)

• MAIN repo tags use SemVer: vMAJOR.MINOR.PATCH.
• Local fork version folders use underscore variant of the same version:
  • v1_0_1, v2_3_3, etc.
• Node mapping namespace suffixes must match folder versions:
  • __koolook_v1_0_1, __koolook_v2_3_3, etc.
• Keep source_ref + pinned_commit in forks/forks_manifest.yaml and UPSTREAM_PIN.yaml.

Upgrade Flow Example (Radiance)

1. Compare current local version (forks/radiance_koolook/versions/v1_0_1) with pinned raw baseline (../ComfyUI-Forks/radiance-v1.0.1-koolook).
2. Pull latest upstream in ../ComfyUI-Forks/radiance-main-upstream.
3. Create a new local version folder in MAIN, e.g. forks/radiance_koolook/versions/v2_3_3.
4. Port/validate modifications.
5. Namespace node IDs for that version.
6. Add new entry/update metadata in forks/forks_manifest.yaml.

Rule of Thumb

• If it is modified production code -> keep in MAIN under forks/.../versions/...
• If it is raw upstream reference -> keep outside MAIN under ../ComfyUI-Forks