ContextQMD
Back to Folo

Desktop Regular Release

.agents/skills/desktop-release/SKILL.md

0.9.05.7 KB
Original Source

Desktop Regular Release

Perform a regular desktop release. This skill handles the full release workflow from the dev branch.

Pre-flight checks

  1. Confirm the current branch is dev. If not, abort with a warning.
  2. Run git pull --rebase in the repo root to ensure the local branch is up to date.
  3. Read apps/desktop/package.json to get the current version and mainHash.

Step 1: Gather changes since last release

  1. Find the last release tag:
    bash
    git tag --sort=-creatordate | grep '^desktop/v' | head -1
  2. Get all commits since that tag on the current branch:
    bash
    git log <last-tag>..HEAD --oneline --no-merges
  3. Categorize commits into:
    • Shiny new things (feat: commits, new features)
    • Improvements (refactor:, perf:, chore: improvements, dependency updates)
    • No longer broken (fix: commits, bug fixes)
    • Thanks (identify external contributor GitHub usernames from commits)

Step 2: Update changelog

  1. Read apps/desktop/changelog/next.md.

  2. Present the categorized changes to the user and draft the changelog content.

  3. Wait for user confirmation or edits before writing.

  4. Write the final content to apps/desktop/changelog/next.md, following the template format:

    markdown
    # What's new in vNEXT_VERSION

## Shiny new things

- description of new feature

## Improvements

- description of improvement

## No longer broken

- description of fix

## Thanks

Special thanks to volunteer contributors @username for their valuable contributions

  5. Keep NEXT_VERSION as the placeholder - it will be replaced by apply-changelog.ts during bump.

Step 3: Commit changelog updates before bump

nbump requires a clean working tree. Commit changelog edits before running bump.

  1. Stage the changelog update:
    bash
    git add apps/desktop/changelog/next.md
  2. Commit it on dev:
    bash
    git commit -m "docs(desktop): prepare release changelog"
  3. If there are no changes to commit, continue without creating an extra commit.

Step 4: Evaluate mainHash

This is critical for determining whether users need a full app update or can use the lightweight renderer hot update.

  1. Check what files changed in apps/desktop/layer/main/ since the last release tag:
    bash
    git diff <last-tag>..HEAD --name-only -- apps/desktop/layer/main/
  2. Also check changes to apps/desktop/package.json fields other than version/mainHash (since package.json is included in the hash calculation):
    bash
    git diff <last-tag>..HEAD -- apps/desktop/package.json

Decision logic:

  • If there are NO changes in layer/main/ and no meaningful package.json changes (only version/mainHash/changelog-related), then mainHash should NOT be updated. Users will get a fast renderer-only hot update.
  • If there are trivial changes in layer/main/ (typo fixes, comment changes, logging tweaks) that don't affect runtime behavior, recommend NOT updating mainHash. Present the changes to the user and ask for confirmation.
  • If there are meaningful changes in layer/main/ (new features, bug fixes, dependency changes, API changes), mainHash MUST be updated. Users will need a full app update.

Present your analysis to the user with:

  • List of changed files in layer/main/
  • A summary of what changed
  • Your recommendation (update or skip mainHash)
  • Ask for explicit confirmation

Step 5: Save old mainHash and execute bump

  1. Save the current mainHash from apps/desktop/package.json for later comparison.
  2. Verify working tree is clean before bump:
    bash
    git status --short
  3. Change directory to apps/desktop/ and run the bump:
    bash
    cd apps/desktop && pnpm bump
  4. This command will:
    • Pull latest changes
    • Apply changelog (rename next.md to {version}.md, create new next.md)
    • Recalculate mainHash and write to package.json
    • Format package.json
    • Bump minor version
    • Commit with message release(desktop): release v{NEW_VERSION}
    • Create branch release/desktop/{NEW_VERSION}
    • Push branch and create PR to main

Step 6: Restore mainHash if skipping update

If Step 4 decided mainHash should NOT be updated, restore the old value now. The bump has already committed, pushed, and created the PR on a new release branch, so we amend the commit and force push. This is safe because the release branch was just created.

  1. Change back to the repo root first (Step 5 left the working directory at apps/desktop/):
    bash
    cd ../..
  2. Ensure you are on the release/desktop/{NEW_VERSION} branch (bump should have switched to it).
  3. Replace the recalculated mainHash with the saved old value in apps/desktop/package.json.
  4. Stage and amend the release commit:
    bash
    git add apps/desktop/package.json && git commit --amend --no-edit
  5. Force push the release branch:
    bash
    git push --force origin release/desktop/{NEW_VERSION}

If Step 4 decided mainHash SHOULD be updated, skip this step entirely — the bump already wrote the correct new value.

Step 7: Verify

  1. Confirm the PR was created successfully by checking the output.
  2. Report the new version number and PR URL to the user.
  3. Summarize:
    • New version: v{NEW_VERSION}
    • mainHash updated: yes/no (and why)
    • Changelog highlights
    • PR URL

Reference

  • Bump config: apps/desktop/bump.config.ts
  • Changelog dir: apps/desktop/changelog/
  • Changelog template: apps/desktop/changelog/next.template.md
  • mainHash generator: apps/desktop/plugins/vite/generate-main-hash.ts
  • Hot updater logic: apps/desktop/layer/main/src/updater/hot-updater.ts
  • CI build workflow: .github/workflows/build-desktop.yml
  • Tag workflow: .github/workflows/tag.yml