Skip to content

docs: add release process guide #9548

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DrJKL merged 4 commits into from
Mar 9, 2026
Merged

docs: add release process guide #9548

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
af9cb5b
docs: add release process guide
christian-byrne Mar 8, 2026
bd50533
docs: expand dual-homed explanation with no-divergence clarification
christian-byrne Mar 8, 2026
c3169f7
docs: condense release-process.md
christian-byrne Mar 8, 2026
4591db6
Merge branch 'main' into docs/release-process-guide
DrJKL Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions docs/release-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# Release Process

How versions are bumped, branches are created, and artifacts are published.

## Version Semantics by Bump Type

All releases start from the same workflow (`release-version-bump.yaml`), but
the downstream effects differ based on bump type and target branch.

### Minor bump on `main` (new development cycle)

A minor bump **freezes** the previous minor into stabilization branches and
starts a new cycle.

```
main: ──A──B──C──D──[bump to 1.42.0]──E──F──G── ...
│
├── core/1.41 (branched from D)
└── cloud/1.41 (branched from D)
```

@coderabbitai coderabbitai Bot Mar 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specifier to fenced code block.

The fenced code block should include a language identifier for proper syntax highlighting and markdown compliance.

📝 Proposed fix 
-```
+```text
 main:  ──A──B──C──D──[bump to 1.42.0]──E──F──G── ...
                   │
                   ├── core/1.41  (branched from D)
                   └── cloud/1.41 (branched from D)
</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 15-15: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/release-process.md` around lines 15 - 20, The fenced diagram block in
docs/release-process.md is missing a language specifier; update the opening
triple-backtick for the block that contains the branch diagram (the block
starting with "main:  ──A──B──C──D──[bump to 1.42.0]──E──F──G── ...") to include
a language tag such as text (e.g., change ``` to ```text) so markdown renderers
apply proper syntax highlighting and the document is compliant.


Commits A–D are the "1.41" work. E–G are new "1.42" development.

The `core/1.41` and `cloud/1.41` branches are created from the commit
**before** the version bump — they capture everything on `main` while it was
at `1.41.x`. This is why the branches are named after the *previous* minor:
they represent the **stabilized 1.41 release line**, not the new 1.42 cycle.

The v1.41.0 GitHub release is published and marked "latest". `core/` and
`cloud/` labels are created for backporting.

### Patch bump on `main` (daily snapshot)

A patch bump on `main` (e.g., `1.42.0` → `1.42.1`) simply publishes. **No
branches are created.** The GitHub release is published and marked "latest".

This is what the nightly cron does — it's a convenience snapshot of `main`.

### Patch bump on `core/X.Y` (hotfix)

A patch bump on a stable branch (e.g., `core/1.41` from `1.41.5` → `1.41.6`)
publishes a hotfix. **No branches are created.** The GitHub release is created
as a **draft** — it must be manually published with "Set as latest release"
**unchecked**, so `main` remains the "latest".

### Where the same commits end up

When a minor bump happens instead of a patch bump, the unreleased commits are
**dual-homed** — they appear in both places:

```
v1.40.1 ── A ── B ── C ── [bump to 1.41.0]
```
Comment on lines +25 to +29

@coderabbitai coderabbitai Bot Mar 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specifier to fenced code block.

The fenced code block should include a language identifier for proper syntax highlighting and markdown compliance.

📝 Proposed fix 
-```
+```text
 v1.40.1 ── A ── B ── C ── [bump to 1.41.0]
</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>

[warning] 51-51: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/release-process.md around lines 51 - 53, Update the fenced code block
surrounding the string "v1.40.1 ── A ── B ── C ── [bump to 1.41.0]" to include a
language specifier (e.g., use text instead of ), so the block is
markdown-compliant and renders with proper syntax highlighting; change the
opening backticks only and keep the content and closing backticks unchanged.


</details>

<!-- fingerprinting:phantom:triton:puma -->

<!-- This is an auto-generated comment by CodeRabbit -->


- **If this were a patch bump** (1.40.1 → 1.40.2): A, B, C become v1.40.2.
- **As a minor bump** (1.40.1 → 1.41.0): A, B, C become v1.41.0 on `main`,
AND they sit on `core/1.40` where they could later ship as v1.40.2 via a
patch bump on that branch.

There's no divergence — it's the same commits in both. The only difference is
whether future work (1.41+ features) gets mixed in, which the branch prevents.
This is intentional — `core/1.40` exists so ComfyUI can stay on the 1.40.x
line and receive patches without jumping to 1.41. The same code ends up in
both places because it was developed during the 1.40 era — 1.41.0 just happens
to be the first release that includes it on `main`.

## Summary Table

| Bump | Target | New branches? | GitHub release |
|---|---|---|---|
| Minor | `main` | ✅ `core/` + `cloud/` for previous minor | Published, "latest" |
| Patch | `main` | ❌ | Published, "latest" |
| Patch | `core/X.Y` | ❌ | **Draft** (uncheck "latest") |
| Prerelease | any | ❌ | Draft + prerelease |

## Backporting

When a fix on `main` needs to go to a stable branch:

1. Add `needs-backport` + version label (e.g., `1.41`) to the merged PR
2. `pr-backport.yaml` cherry-picks the merge commit and creates a backport PR
3. If conflicts arise, the workflow comments with details and an agent prompt

## Publishing

Every merged PR with the `Release` label triggers `release-draft-create.yaml`:

| Channel | Package |
|---|---|
| GitHub Releases | `dist.zip` |
| PyPI | `comfyui-frontend-package` |
| npm | `@comfyorg/comfyui-frontend-types` |

@coderabbitai coderabbitai Bot Mar 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify package names match repository configuration

echo "Checking npm package name..."
if [ -f "package.json" ]; then
  npm_name=$(jq -r '.name' package.json)
  echo "Found in package.json: $npm_name"
  if [ "$npm_name" = "@comfyorg/comfyui-frontend-types" ]; then
    echo "✓ npm package name matches documentation"
  else
    echo "⚠ npm package name differs from documentation"
  fi
fi

echo ""
echo "Checking PyPI package name..."
for pyfile in pyproject.toml setup.py setup.cfg; do
  if [ -f "$pyfile" ]; then
    echo "Found: $pyfile"
    case "$pyfile" in
      pyproject.toml)
        if grep -q "name.*comfyui-frontend-package" "$pyfile"; then
          echo "✓ PyPI package name matches documentation"
        else
          echo "PyPI package name in $pyfile:"
          grep "name" "$pyfile" | head -1
        fi
        ;;
      setup.py)
        if grep -q "name.*comfyui-frontend-package" "$pyfile"; then
          echo "✓ PyPI package name matches documentation"
        else
          echo "PyPI package name in $pyfile:"
          grep "name" "$pyfile" | head -1
        fi
        ;;
    esac
  fi
done

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 225

🏁 Script executed:

# Find configuration files related to PyPI/Python packaging
find . -type f \( -name "pyproject.toml" -o -name "setup.py" -o -name "setup.cfg" -o -name "*.toml" \) 2>/dev/null | head -20

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 105

🏁 Script executed:

# Search for references to the PyPI package name in the repository
rg "comfyui-frontend-package" --type md --type txt --type toml --type yaml -i

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 296

🏁 Script executed:

# Check if there's a separate types package or verify npm package details
cat package.json | jq '.description, .version, .keywords' 2>/dev/null

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 130

🏁 Script executed:

cat ./comfyui_frontend_package/setup.py | head -30

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 347

Fix the npm package name in the documentation.

The npm package name should be @comfyorg/comfyui-frontend, not @comfyorg/comfyui-frontend-types. The -types suffix does not exist in the actual package.json. The PyPI package name comfyui-frontend-package is correct.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/release-process.md` around lines 84 - 89, Update the npm package name
entry in the release process docs: replace the incorrect package string
`@comfyorg/comfyui-frontend-types` in the "Channel | Package" table with the
correct `@comfyorg/comfyui-frontend`, leaving the rest of the table (GitHub
Releases `dist.zip` and PyPI `comfyui-frontend-package`) unchanged.

## Bi-weekly ComfyUI Integration

`release-biweekly-comfyui.yaml` runs every other Monday:

1. Checks ComfyUI's `requirements.txt` for the current frontend version
2. If the next `core/` branch has unreleased commits, triggers a patch bump
3. Creates a draft PR to `Comfy-Org/ComfyUI` updating `requirements.txt`

## Workflow Reference

| Workflow | Purpose |
|---|---|
| `release-version-bump.yaml` | Bump version, create Release PR |
| `release-draft-create.yaml` | Build + publish to GitHub/PyPI/npm |
| `release-branch-create.yaml` | Create `core/` and `cloud/` branches (minor/major only) |
| `release-biweekly-comfyui.yaml` | Auto-patch + ComfyUI requirements PR |
| `pr-backport.yaml` | Cherry-pick fixes to stable branches |
| `cloud-backport-tag.yaml` | Tag cloud branch merges |
Loading