hmg-comfy/ComfyUI_ETK_LTXV_Timeline_Editor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8cb530954d4ee7cc38e4972373f57e162e0864a9
ComfyUI_ETK_LTXV_Timeline_E…/REGISTRY_RELEASE_RESEARCH.md
T
Hopping Mad Games 869537cefd Release standalone timeline editor 1.0.0
2026-08-26 09:55:12 -06:00

28 KiB
Raw Blame History

ComfyUI Registry Release Research for ComfyUI_ETK_LTXV_Timeline_Editor

Research date: 2026-08-26

Scope: current official publication process for ComfyUI custom node packs, using official ComfyUI documentation, the official Registry site/repository, and current official tooling source/schema. Local pack inspection was read-only.

Primary Official Sources

Executive Summary

The current official flow is:

  1. Create a Comfy Registry account and a publisher.
  2. Create a publisher-scoped Registry publishing API key.
  3. Add a root pyproject.toml with the current Comfy metadata schema.
  4. Optionally add .comfyignore to control what ships.
  5. Publish with comfy node publish, or wire the official GitHub Action around that same command. [Source: https://docs.comfy.org/registry/publishing]

Published versions are immutable once released, and semver is required. Bad releases are handled by publishing a newer version, deprecating the broken one, or deleting it through the registry controls/API. [Source: https://docs.comfy.org/registry/overview ; https://docs.comfy.org/api-reference/registry/update-changelog-and-deprecation-status-of-a-node-version ; https://docs.comfy.org/api-reference/registry/unpublish-delete-a-specific-version-of-a-node]

For this local pack, the literal Registry submission blockers are the missing required pyproject.toml fields, publisher setup/token, repository URL, and semver version. Separate release-readiness gaps include legal/licensing metadata, deterministic packaging controls, CI/publish automation, and the fact that the pack is not currently in its own tracked Git repository state. Local inspection only.

1. Exact Current Publication Workflow and Required Accounts/Permissions

Official workflow

  1. Create or sign into a Registry account. The registry site explicitly exposes sign-in and creator publishing. [Source: https://registry.comfy.org/]
  2. Create a publisher. The publisher ID is globally unique, appears after @ on the profile page, and cannot be changed later because it becomes part of the node URL. [Source: https://docs.comfy.org/registry/publishing]
  3. Create a Registry publishing API key for that publisher and store it safely. It is the credential used by CLI and GitHub Actions publishing. [Source: https://docs.comfy.org/registry/publishing]
  4. Add root metadata in pyproject.toml. The publishing docs explicitly point authors to comfy node init to generate the scaffold. [Source: https://docs.comfy.org/registry/publishing]
  5. Optionally add .comfyignore at repo root to exclude tests, docs, design files, and other dev-only artifacts from the published archive. [Source: https://docs.comfy.org/registry/publishing]
  6. Publish either:

Required accounts and permissions

Inference: for a brand-new node publication, the public docs do not currently state that GitHub admin rights are required by the registry itself, but GitHub repository control is still practically required if you want to configure repository secrets and GitHub Actions publishing.

2. Required and Recommended Repository Files, Metadata, and Validation Commands

Required current metadata file and schema

The required metadata file is pyproject.toml at repository root. The official Comfy schema is split across [project] and [tool.comfy]. [Source: https://docs.comfy.org/registry/specifications]

Required today:

Recommended today:

Frontend compatibility metadata

If the pack ships frontend JS, the current public spec shows frontend compatibility expressed via a comfyui-frontend-package... dependency string in [project].dependencies; the official CLI source currently parses that special dependency into supported_comfyui_frontend_version metadata. [Source: https://docs.comfy.org/registry/specifications ; https://raw.githubusercontent.com/Comfy-Org/comfy-cli/main/comfy_cli/registry/config_parser.py]

Archive inclusion and exclusion controls

Current official CLI commands

Official docs explicitly document:

Current official CLI source also exposes:

Current CLI validation source details:

GitHub Actions publishing

The public publishing doc still shows an explicit checkout step and a sample using actions/checkout@v7, but the current official publish-node-action source already performs checkout internally with actions/checkout@v4 unless skip_checkout=true, sets up Python with actions/setup-python@v5, installs comfy-cli, and runs comfy node publish --token .... [Source: https://docs.comfy.org/registry/publishing ; https://raw.githubusercontent.com/Comfy-Org/publish-node-action/main/action.yml]

Inference: the action source is the safer source of truth than the older inline docs snippet when they disagree.

3. Versioning, Git Tags/Releases, CI, Ownership, License, Dependency, Frontend, and Security Expectations

Versioning

Inference: because registry versions are immutable, every public release should map to a single Git commit and a permanent Git tag. A GitHub release is not currently documented as required by Comfy, but it is the cleanest way to preserve provenance for the uploaded artifact.

CI expectations

Inference: for a node pack with both Python and browser code, the minimum practical CI set is syntax/lint/unit checks plus at least one Comfy workflow smoke test.

Ownership expectations

Inference: if this pack is intended to replace or supersede a previously distributed package, repository continuity and clear transfer-of-ownership evidence matter even when the new release path is a brand-new registry submission.

License expectations

Inference: for public release, a real LICENSE file and matching license metadata should be treated as mandatory, even if the docs still call it optional, because legal ambiguity is avoidable and unnecessary.

Dependency expectations

Frontend expectations

Security expectations

4. How Backward-Compatible Workflow Node Keys Affect Publication

The workflow-critical node identity is the NODE_CLASS_MAPPINGS key, not the human-friendly display name. The lifecycle docs state that NODE_CLASS_MAPPINGS maps unique node names to node classes, and those names must be unique across the install. [Source: https://docs.comfy.org/custom-nodes/backend/lifecycle]

For this pack, keeping the workflow node key as ETKLTXVTimelineImageEditor is the correct backward-compatibility move for existing saved workflows. Local inspection confirms the pack currently preserves that key in __init__.py, and the README explicitly says existing workflows load without migration. Local inspection only.

Display-name changes are low risk because NODE_DISPLAY_NAME_MAPPINGS can change the UI label without changing the underlying workflow key. [Source: https://docs.comfy.org/custom-nodes/backend/lifecycle]

If the underlying node key ever changes in a future release, the current official migration path is node replacement registration with io.NodeReplace, including old_node_id, input mapping, output mapping, and old_widget_ids when widget order matters. [Source: https://docs.comfy.org/custom-nodes/backend/node-replacement]

Inference: the registry API exposes preempted_comfy_node_names on node objects, which suggests the registry tracks legacy Comfy node-name relationships internally, but I did not find current publisher-facing documentation describing an author-managed metadata field for setting that directly. Supporting API references: https://docs.comfy.org/api-reference/registry/update-a-specific-node and https://docs.comfy.org/api-reference/registry/retrieve-a-node-by-comfyui-node-name

Practical publication impact:

  • Do not rename ETKLTXVTimelineImageEditor for the first registry release if backward compatibility matters.
  • If you later need a rename, treat it as a migration release, not a cosmetic cleanup.
  • Keep the package ID and the node key conceptually separate: package/repository metadata can evolve more safely than workflow node IDs.

5. Local Pack Gap Analysis

Inspected path: /CSA/work/ComfyUI_ETK_LTXV_Timeline_Editor

Literal Registry submission blockers

  1. No pyproject.toml exists.

    • This blocks the current official publish flow because the registry metadata schema is missing entirely. Local inspection only.

  2. No registry publisher metadata is present.

    • There is no PublisherId, and no publisher PAT can be inferred from the pack. Local inspection only.

  3. No required repository URL metadata exists.

  4. No release version has been established.

Release-quality blockers and recommended gates

These are not all mandatory Registry fields. They should still be resolved before this pack's first public release.

  1. The pack is not currently in a deterministic release-packaging state.

  2. No .comfyignore exists.

    • .comfyignore is optional, but in the current non-Git-tracked fallback state its absence can sweep development artifacts into the archive. Local inspection only.

  3. No license file or license metadata exists.

  4. No explicit compatibility metadata exists.

    • requires-python, requires-comfyui, and frontend compatibility constraints are all optional or recommended in the official spec, but declaring tested ranges reduces installation ambiguity. [Source: https://docs.comfy.org/registry/specifications ; local inspection]

  5. No dependency metadata exists.

    • The code imports numpy, torch, PIL, and folder_paths; there is also an optional scipy fallback path.
    • A release review must distinguish ComfyUI-provided runtime modules from third-party packages that actually need declaration. Missing dependency metadata is only a publication blocker if the pack requires an undeclared external package. Local inspection and inference.

  6. No CI workflow exists.

    • CI is recommended by the official docs rather than required for publication. There is currently no .github/workflows content for validation or publish automation. [Source: https://docs.comfy.org/registry/cicd ; local inspection]

Recommended but not strictly hard blockers

  1. Add in-app node documentation under web/docs/ETKLTXVTimelineImageEditor.md or locale-specific variants. [Source: https://docs.comfy.org/custom-nodes/help_page]
  2. Add example_workflows/ with at least one working JSON and optional thumbnail. [Source: https://docs.comfy.org/custom-nodes/workflow_templates]
  3. Add subgraphs/ only if the editor has reusable graph blueprints worth exposing. [Source: https://docs.comfy.org/custom-nodes/subgraph_blueprints]
  4. Add Documentation and "Bug Tracker" URLs in [project.urls]. [Source: https://docs.comfy.org/registry/specifications]
  5. Add OS and accelerator classifiers. [Source: https://docs.comfy.org/registry/specifications]
  6. Add icon and banner URLs after assets exist. Note that the docs are currently inconsistent: the spec says icon should be square and at most 400x400, while the publishing-page scaffold comment still says MAX. 800x400px. The spec page is the safer source of truth. [Source: https://docs.comfy.org/registry/specifications ; https://docs.comfy.org/registry/publishing]
  7. Add a real changelog policy and release notes process. Inference.

Positive findings from local read-only inspection

  • The pack already preserves the workflow node key ETKLTXVTimelineImageEditor in NODE_CLASS_MAPPINGS. Local inspection only.
  • The README already documents that compatibility decision. Local inspection only.
  • WEB_DIRECTORY = "./web" is present, so the pack is structurally aligned with Comfy's current frontend-loading model. Local inspection only.
  • I did not find obvious prohibited eval, exec, runtime pip install, or code obfuscation patterns in the inspected code. Local inspection only.
  • Python syntax compilation passed locally with python3 -m py_compile ..., and JavaScript syntax checks passed with node --check .... Local inspection only.
  • pytest could not be executed in this environment because pytest is not installed here, so test execution remains unverified. Local inspection only.

6. Minimal Ordered Release Checklist

  1. Put the pack into its own Git-tracked public release repository, or otherwise ensure that the exact release contents are fully Git-tracked from the pack root.
  2. Decide the permanent package ID ([project].name) and permanent publisher ID strategy.
  3. Create the Registry account, create the publisher, and create a publisher PAT. [Source: https://docs.comfy.org/registry/publishing]
  4. If this should inherit ownership from a migrated legacy listing, verify whether the official claim flow is needed and perform it with the repository admin account. [Source: https://docs.comfy.org/registry/claim-my-node]
  5. Add pyproject.toml with:
    • required name, version, Repository, and PublisherId
    • explicit license
    • explicit requires-python
    • explicit requires-comfyui
    • explicit dependency declarations
    • explicit frontend compatibility declaration if you intend to support current frontend ranges. [Source: https://docs.comfy.org/registry/specifications]
  6. Add LICENSE.
  7. Add .comfyignore so the published archive excludes tests, caches, and dev-only assets. [Source: https://docs.comfy.org/registry/publishing]
  8. Add CI:
  9. Add user-facing release support assets:
    • node docs
    • example workflows
    • bug tracker/documentation URLs
    • optional icon/banner
  10. Run comfy node validate and comfy node pack; inspect the archive contents before the first publish. [Source: https://raw.githubusercontent.com/Comfy-Org/comfy-cli/main/comfy_cli/command/custom_nodes/command.py]
  11. Tag the release commit before publish. Inference.
  12. Publish with comfy node publish or the official publish action. [Source: https://docs.comfy.org/registry/publishing ; https://raw.githubusercontent.com/Comfy-Org/publish-node-action/main/action.yml]
  13. Verify:
  • registry page renders correctly
  • install works in ComfyUI-Manager
  • existing workflows using ETKLTXVTimelineImageEditor still load
  • frontend JS loads correctly on a supported ComfyUI/frontend version.

7. Minimal Rollback and Update Process

Update process

  1. Make the code change.
  2. Keep the node key stable unless the release is an intentional migration release.
  3. Bump semver in pyproject.toml. [Source: https://docs.comfy.org/registry/specifications]
  4. Re-run local validation and CI.
  5. Publish the new version.
  6. Verify install and workflow compatibility in ComfyUI-Manager.

Rollback process

Because published versions are immutable, rollback is not "replace the broken artifact." The current official options are: [Source: https://docs.comfy.org/registry/overview ; https://docs.comfy.org/api-reference/registry/update-changelog-and-deprecation-status-of-a-node-version ; https://docs.comfy.org/api-reference/registry/unpublish-delete-a-specific-version-of-a-node]

  1. Publish a fixed higher version as the preferred recovery path.
  2. Deprecate the bad version through the Registry UI or PUT /publishers/{publisherId}/nodes/{nodeId}/versions/{versionId} with deprecated=true and a changelog/deprecation message.
  3. If necessary, unpublish the bad version with DELETE /publishers/{publisherId}/nodes/{nodeId}/versions/{versionId}.
  4. If the whole node listing must be removed, the API also exposes node deletion at the publisher/node level. [Source: https://docs.comfy.org/registry/api-reference/nodes/delete-a-specific-node]

Inference: for trust and reproducibility, deprecate first and keep a visible explanation whenever possible; use deletion only when the release is invalid or should not remain publicly installable.

8. Specific Current Gaps To Resolve For This Pack Before First Release

These are the concrete items I would resolve before attempting a first registry publish:

  • Create a dedicated tracked release repository state for the pack.
  • Add pyproject.toml.
  • Choose the permanent package ID.
  • Choose the permanent publisher ID and create the PAT.
  • Add a license file and metadata.
  • Declare Python dependencies and compatibility ranges.
  • Declare ComfyUI compatibility via requires-comfyui.
  • Declare frontend compatibility because this pack ships JS.
  • Add .comfyignore.
  • Add CI.
  • Add at least one example workflow.
  • Add node docs.
  • Decide whether icon/banner assets are ready.
  • Confirm whether any legacy listing or claim path needs to be reconciled before publication.

9. Notes on Current Docs vs Tooling Mismatches

  1. The publishing page's sample comment still says icon max 800x400, while the spec page says icons should be square and max 400x400. I would follow the spec page. [Source: https://docs.comfy.org/registry/publishing ; https://docs.comfy.org/registry/specifications]
  2. The publishing page's GitHub Actions snippet shows explicit checkout with actions/checkout@v7, while the current official action source already performs checkout with actions/checkout@v4 unless skip_checkout=true. I would follow the action source. [Source: https://docs.comfy.org/registry/publishing ; https://raw.githubusercontent.com/Comfy-Org/publish-node-action/main/action.yml]
  3. The public publishing page documents init and publish, but the current official CLI source also provides validate and pack. I would use both before first release. [Source: https://docs.comfy.org/registry/publishing ; https://raw.githubusercontent.com/Comfy-Org/comfy-cli/main/comfy_cli/command/custom_nodes/command.py]
  4. The current CLI source supports additional version-resolution behavior not clearly documented on the public spec page. For a first release, static project.version = "X.Y.Z" is the lowest-risk path. [Source: https://raw.githubusercontent.com/Comfy-Org/comfy-cli/main/comfy_cli/registry/config_parser.py ; inference]

10. Main-Agent Verification

After restoring this report from the research agent's durable session record, the main agent independently re-opened the current official publishing page, pyproject.toml specification, CI/CD page, and publish-node-action definition on 2026-08-26. The required metadata, publisher/token flow, .comfyignore behavior, CLI/action publication paths, and documented action/docs mismatch described above were confirmed.

The live extracted pack on csa-host also passed its contract test (3 passed in 1.22s), Python compilation, and JavaScript node --check validation. This supersedes the research agent's narrower note that pytest was unavailable inside its own isolated research environment.

Reference in New Issue View Git Blame Copy Permalink