StyleRef-styleref-comfyui/RELEASING.md

Releasing an update

For an agent or contributor picking this up cold: this is the repeatable flow for shipping a change to users — a node fix, a new workflow template, updated artwork, anything. It is distinct from the one-time steps that stood this repo up in the first place (those live in the private monorepo and don't apply again).

If this repo reached you as a git submodule inside StyleRef-Webapp, work here, in the submodule — not by editing a plain copy of these files somewhere else. A commit made outside this repo publishes nothing.

1. Make the change

Edit the source. If you touched a workflow's shape (nodes, links, layout, subjects, the style it loads) rather than hand-editing JSON, regenerate:

python scripts/build_workflows.py

The committed workflows/*.json files must match the generator's output — CI fails the build otherwise, and a hand-edit to the JSON will just be overwritten the next time someone runs the script.

2. Bump the version — four places, together

There is no tooling for this step; it is easy to update three and miss the fourth, so check all four:

File	What to change
pyproject.toml	version = "x.y.z"
__init__.py	_FALLBACK_VERSION = "x.y.z"
styleref_api.py	USER_AGENT = "styleref-comfyui/x.y.z (...)"
README.md	The [StyleRef] vx.y.z — 5 nodes registered line in Install

tests/test_api.py::test_version_strings_agree_with_pyproject fails if the first three disagree — trust it, but it can't see the README line, so check that one by eye.

Use semver. The publish workflow (.github/workflows/publish.yml) rejects a tag that doesn't exactly match pyproject.toml's version.

3. Verify locally

ruff check .
pytest tests/ -q

If the change touches web/styleref.js, at minimum run node --check web/styleref.js — there is no JS test harness, so a syntax check is the only automated signal before it reaches a real ComfyUI frontend.

4. Commit and push, in this repo

git add -A
git commit -m "..."
git push origin main

5. Tag the commit you just pushed

git tag -a vX.Y.Z -m "..."
git push origin vX.Y.Z

The tag push fires Publish to Comfy Registry (.github/workflows/publish.yml): it re-checks the tag against pyproject.toml, lints, runs the test suite, then calls Comfy-Org/publish-node-action with the REGISTRY_ACCESS_TOKEN secret. Watch it in the Actions tab or with gh run watch.

A branch-protection ruleset on main requires 3 status checks that a direct push can't have satisfied yet (see the public-repo branch ruleset convention). The push above will report "Bypassed rule violations" — that's expected, not an error, as long as the account pushing is on the bypass list.

6. Bump the pointer in the monorepo

A tag and a Registry publish are invisible to StyleRef-Webapp until its submodule pointer moves. Back in the monorepo root:

git add connectors/styleref-comfyui
git commit -m "chore(comfyui): bump connector to vX.Y.Z (<why>)"
git push origin main

Skipping this step is the easy mistake — nothing errors, the monorepo just quietly keeps pointing at the old commit. git status in the monorepo shows a moved submodule as a one-line change; git diff --submodule shows which commits moved.

7. Confirm the release actually landed — don't trust a green check alone

A successful publish workflow proves the build succeeded, not that the Registry did the right thing with it, and not that ComfyUI reads what you shipped the way you assumed. Check the real state:

# Per-version status (Pending → Active is normal and can take a while;
# Flagged sometimes clears on its own — see the note below)
curl -s https://api.comfy.org/nodes/styleref-comfyui/versions | python3 -m json.tool

# Node-level: which version is actually live for install
curl -s https://api.comfy.org/nodes/styleref-comfyui | python3 -m json.tool

If the change affects what's inside the shipped package (thumbnails, a new file, .comfyignore), download and inspect the actual published archive rather than trusting what you intended to ship:

curl -sL "https://cdn.comfy.org/styleref/styleref-comfyui/X.Y.Z/node.zip" -o node.zip
unzip -l node.zip

This caught two real bugs in past releases: model-download metadata that was declared in the wrong JSON location (present in the repo, silently ignored by ComfyUI), and template thumbnails shipped as .webp when custom node packs are only read as .jpg — both looked correct in CI and in the archive listing, and only showing up wrong in a running ComfyUI proved it.

On NodeVersionStatusFlagged

Comfy's scanner has flagged every version of this pack at some point, including versions identical to ones that were flagged and later cleared on their own — this looks like a transient state in their pipeline, not a verdict on the code. Don't rush to change anything or re-publish in response to a flag by itself. Give it time and re-check; if it's still flagged after a day or two with no NodeVersionStatusActive version anywhere, that's when it's worth asking in the Comfy Discord (icon in the registry.comfy.org header) rather than guessing at a code change.

If the ComfyUI-Manager listing needs updating too

custom-node-list.json in Comfy-Org/ComfyUI-Manager is a second, separate listing from the Comfy Registry — Manager's "default channel," predating the Registry and not auto-synced from it. A Registry publish does not update it. If this pack's entry there (id: "styleref-comfyui") ever needs a description or metadata change, that is its own PR against that repo, not something this release flow touches.