malkuthro-ComfyUI-Koolook/docs/reference/versioning.md

Versioning — three numbers, three meanings

This codebase carries three independent version numbers that often get confused. They mean different things, bump on different schedules, and live in different places.

At a glance

Axis	What it is	Where it lives	Example
Pack version	The Koolook release that ships to GitHub + Comfy Registry. Semver.	pyproject.toml version = "X.Y.Z", CHANGELOG.md ## [X.Y.Z]	0.2.0
Fork wrapper version	A slot under versions/ that holds Koolook's modified code for a particular upstream baseline. Underscored.	forks/<fork>/versions/vX_Y_Z/ directory name + the NAMESPACE_SUFFIX constant inside it	v2_3_3
Upstream pinned commit	The exact commit of the upstream third-party repo that the fork wrapper is matched to. SHA.	forks/<fork>/versions/vX_Y_Z/UPSTREAM_PIN.yaml, forks/forks_manifest.yaml, forks/THIRD_PARTY.md	f262f47ddfda01ece154bf80c22769b1e4cef795

A current snapshot reads: "Koolook 0.2.0 ships the v2_3_3 Radiance fork wrapper, which is pinned to upstream Radiance commit f262f47." All three are unrelated numbers that happen to all describe the same release.

When each one bumps

Pack version (0.2.0 → 0.2.1 / 0.3.0 / 1.0.0)

Bumps on every release of the Koolook pack itself. Drives the Comfy Registry publish workflow. Follow docs/maintainers/releasing.md for the canonical procedure.

• Patch (0.2.0 → 0.2.1): bug fixes, internal refactors, no surface change.
• Minor (0.2.0 → 0.3.0): new nodes, new node options, anything that adds surface but doesn't break existing workflows.
• Major (0.2.0 → 1.0.0): only after a v2-style breaking change has shipped (a removed-after-deprecation node ID, an INPUT_TYPES change a saved workflow can't tolerate, etc.).

Fork wrapper version (v2_3_3 → v2_4_0 / v2_3_4)

Bumps when upstream releases a new version we want to track AND the new upstream version requires meaningfully different wrapper code.

Two patterns, decided per-fork:

• In-place upgrade (used by Radiance Koolook today). All exposed node IDs are listed in SKIP_VERSION_SUFFIX so the user-facing IDs are stable across versions (e.g. Easy_hdr_VAE_encode stays as itself whether the wrapper is v2_3_3 or v2_4_0). When upstream bumps, the whole versions/v2_3_3/ directory gets renamed to versions/v2_4_0/ in-place; there's no parallel coexistence because both versions would collide on the same ID. Saved workflows continue loading because the ID didn't change.
• Versioned coexistence. Node IDs carry the __koolook_vX_Y_Z suffix (the default behavior unless explicitly added to SKIP_VERSION_SUFFIX). When upstream bumps, the new versions/v2_4_0/ is added alongside the old one. Both are registered simultaneously for one release cycle. Old workflows keep loading via the suffixed old ID; new workflows can adopt the new suffixed ID. The old version is removed in the next release.

Upstream pinned commit (f262f47 → some new SHA)

Bumps when we re-sync the wrapper against a newer upstream commit. Recorded in:

• forks/<fork>/versions/<vX_Y_Z>/UPSTREAM_PIN.yaml (the per-version pin)
• forks/forks_manifest.yaml (the project-level fork inventory)
• forks/THIRD_PARTY.md (the human-readable attribution + change notes)

A new pinned commit may or may not require a new fork wrapper version — small upstream patches can land at the same wrapper slot if our wrapper code doesn't have to change. Bigger upstream releases usually warrant a new wrapper version too.

Public node-ID versioning (the _v2 rule)

Scope. This section is mandatory for fork nodes (anything under forks/, like the Easy_hdr_VAE_* example used below) — they keep full back-compat discipline by default. For Koolook-created nodes (the root k_*.py custom nodes) it is opt-in: by default a breaking change is made in place — rename or alter the existing ID, note it in the CHANGELOG, done — with no _v2 suffix and no deprecation cycle, unless the maintainer asked to check backward compatibility. See CLAUDE.md → Change management.

Independent of the three axes above, individual node IDs can carry a public version suffix when a breaking change forces it:

• Original ID (no suffix): Easy_hdr_VAE_encode. Stays this forever.
• Bumped ID after a breaking change: Easy_hdr_VAE_encode_v2. Only introduced when the original would otherwise break saved workflows.
• Both IDs register simultaneously for one full release cycle (the old one displays as Easy HDR VAE Encode (Koolook, v1 — please migrate) during this window).
• Old ID is dropped one release later. Pack version goes major (1.0.0) to signal the breakage.

This is the rare path. Most version changes don't need it because either the change isn't actually breaking, or the fork wrapper version mechanism above already handles the back-compat.

Which skill / doc owns which axis

Axis	Skill	Doc
Pack version	(none, manual via release PR)	docs/maintainers/releasing.md
Fork wrapper version	docs-sync (string-sweep), add-external-fork (initial setup)	forks/README.md, docs/maintainers/node-versioning.md
Upstream pinned commit	(none — manual edit to UPSTREAM_PIN.yaml + forks_manifest.yaml)	forks/THIRD_PARTY.md
Node-ID _v2 suffix	(none — manual code change with deprecation alias)	(this document)

Example — a hypothetical Radiance v2.4.0 release

Suppose upstream Radiance ships v2.4.0. We re-sync and the wrapper code changes only slightly — same node IDs, same interface. The bumps:

• Upstream pinned commit: f262f47… → whatever the v2.4.0 release commit is. Update UPSTREAM_PIN.yaml, forks_manifest.yaml, THIRD_PARTY.md.
• Fork wrapper version: v2_3_3 → v2_4_0. Rename versions/v2_3_3/ to versions/v2_4_0/. Update NAMESPACE_SUFFIX and DISPLAY_SUFFIX constants inside. Update parent __init__.py import. Rename matching docs folder docs/user_guide/nodes/radiance_koolook_v2_3_3/ → radiance_koolook_v2_4_0/. Update inline references via docs-sync v2_3_3 v2_4_0.
• Pack version: 0.2.0 → 0.3.0. Cut a release PR per releasing.md.
• Node IDs: unchanged (stable IDs). No _v2 suffix introduced. Saved workflows keep loading.

If the v2.4.0 wrapper required a behaviorally breaking change to one of the node IDs — say Easy_hdr_VAE_encode now returns a different shape that downstream samplers can't handle — only then would we add Easy_hdr_VAE_encode_v2 and start the deprecation cycle.

See also

• docs/maintainers/releasing.md — pack version release procedure.
• docs/maintainers/node-versioning.md — the rules for safely changing INPUT_TYPES / RETURN_TYPES / class names without breaking saved workflows.
• forks/THIRD_PARTY.md — upstream attribution and change notes for each fork.
• forks/forks_manifest.yaml — machine-readable fork inventory.
• .claude/skills/docs-sync/SKILL.md — the find-and-replace skill for fork-version bumps.