Skip to content

RELEASE.md

Latest commit

 

History

History
152 lines (121 loc) · 7.77 KB

RELEASE.md

File metadata and controls

152 lines (121 loc) · 7.77 KB
Raw

Release

How FlupCode is versioned and released.

Versioning

  • Semantic versioning: MAJOR.MINOR.PATCH, tagged as flupcode-vX.Y.Z. The flupcode- prefix avoids colliding with upstream OpenCode tags.
  • The tag is the source of truth. Keep packages/harness/package.json and packages/harness-desktop/package.json versions in sync with the tag.
  • The harness About dialog shows packages/harness's version.
  • harness-server is private and published as no artifact of its own, but it is compiled into the desktop app as an extra resource, so it ships with every release and is versioned with the rest. It joined at 1.8.0, having drifted to 1.2.0 while it was unreleased.

What ships

Artifact Source Status
Web bundle (flupcode-web.zip) packages/harness/dist published by CI
Desktop installers (unsigned) packages/harness-desktop published by CI; signing blocked (F5-4)
flupcode CLI binaries packages/flupcode-cli published by CI

Cutting a release

  1. Update the versions (harness, harness-desktop, harness-server, remote, relay, flupcode-cli, bridge-extension) and the lockfile on a branch, and open a pull request: main is protected, so nothing is pushed to it directly.

    git switch -c release-X.Y.Z origin/main
# set the seven package.json versions, then:
npm_config_registry="https://registry.npmjs.org/" bun install
git commit -am "chore: bump version to X.Y.Z"
git push -u origin release-X.Y.Z
gh pr create --base main --title "chore: bump version to X.Y.Z"

  2. Once CI is green, merge it with rebase, then tag the merged commit on origin/main (never a local commit) and push the tag:

    gh pr merge <number> --rebase
git fetch origin
git tag flupcode-vX.Y.Z origin/main
git push origin flupcode-vX.Y.Z

    Stop at the first failure (for example with set -eo pipefail in a script): a tag pushed after a rejected push starts a release from a commit that is not on main.

  3. .github/workflows/release.yml runs on the tag. Its first job, tested, requires that harness.yml's gate passed on the tagged commit (.github/scripts/release-gate.sh): it waits for a run still going, and a commit whose gate failed, was cancelled or never ran builds nothing. Pushes to main no longer cancel each other's harness run, so every commit there keeps its verdict. Then it opens the release as a draft, and then each job builds and publishes its own part of it, in parallel: the web bundle, the five flupcode CLI binaries, and the desktop installers per platform. A verify job reads the update manifests (latest*.yml) off the draft and fails if any file they name is not an asset, and only then is the draft published (--latest).

    Nothing is read back from the Actions artifact store to publish it, and no job waits on another's upload, so a release takes about six minutes — the Windows installer is the long part. When GitHub's asset endpoint is slow for a file, only that platform's job waits. A release that fails halfway stays a draft, so releases/latest keeps serving the previous one; fix the cause and gh run rerun <run-id> --failed re-publishes over the same assets (--clobber).

  4. Add a short user-facing summary above the generated notes (what changed, how to update, and the unsigned-build note for macOS):

    gh release edit flupcode-vX.Y.Z --notes-file notes.md

    The web app (app.flupcode.com) deploys when this bump reaches main: its Vercel build only runs for a commit that changes packages/harness/package.json's version. The landing deploys from main whenever it changes (see "Deploys" in CONTRIBUTING.md).

  5. Verify with:

    gh release view flupcode-vX.Y.Z

Manual fallback

bun install
bun run --cwd packages/harness typecheck
bun run --cwd packages/harness test
bun run --cwd packages/harness build
(cd packages/harness/dist && zip -r ../../../flupcode-web.zip .)
gh release create flupcode-vX.Y.Z flupcode-web.zip --title "FlupCode vX.Y.Z" --generate-notes

Desktop

Installers are published on every release and the app auto-updates from GitHub Releases (electron-updater). They are not signed or notarized (F5-4, blocked on Apple and Windows certificates): macOS shows "FlupCode Not Opened" and needs Open Anyway or removing the quarantine flag, and Windows shows SmartScreen. See USAGE.md.

Integrity (HE-05)

  • What ships is what CI tested. The tested job above: no gate on the tagged commit, no release.
  • Built for the architecture it claims. The app ships three sidecars: the harness server, the macOS speech helper and the Chromium the harness drives. Each is built or fetched once per architecture electron-builder packages on that OS (build.<os>.target[].arch, read by packages/harness-desktop/scripts/archs.mjs) into a folder named after it (harness-server/dist/<arch>/, out/speech/<arch>/, browsers/<arch>/), and extraResources takes the matching one with ${arch}. The x64 Mac app used to carry the build machine's arm64 server, helper and browser. Check a build with file on FlupCode.app/Contents/Resources/harness-server/flupcode-harness.
  • The engine is the one pinned. The desktop and the CLI fetch the OpenCode binary at first use and check it against the sha512 committed beside the version (see UPSTREAM.md).
  • Auto-update checks no signature. electron-updater compares the download with the sha512 in latest*.yml, which comes from the same release, and the unsigned Mac build installs the zip itself and clears its quarantine. Anyone who can publish a release can ship an update; only signing (F5-4) closes that.

Icon geometry

Desktop, PWA and landing icons are generated, never hand-edited:

swift script/branding.swift [source.png]

(macOS only, AppKit.) Source of truth: assets/flupcode-tentative-logo.png on a #FFEDD5 plate. The approved geometry (defined in script/branding.swift targets) is:

Target Canvas Plate Artwork
packages/harness-desktop/build/icon.png (Windows/Linux) 1024x1024 full-bleed fraction: 0.60 by width (~614x779)
packages/harness-desktop/build/icon-mac.png (macOS grid) 1024x1024 scale: 0.805 (824/1024) fraction: 0.60 (~494x627)
packages/harness/public/apple-touch-icon.png 180x180 full-bleed fraction: 0.52 (~93x118)
packages/harness/public/icon-192.png 192x192 full-bleed fraction: 0.52 (~99x126)
packages/harness/public/icon-512.png 512x512 full-bleed fraction: 0.52 (~266x337)
packages/harness/public/icon-maskable-512.png 512x512 full-bleed fraction: 0.50 (~256x324, maskable safe zone)
packages/landing/assets/apple-touch-icon.png 180x180 full-bleed fraction: 0.52 (~93x118)
packages/landing/assets/icon-192.png 192x192 full-bleed fraction: 0.52 (~99x126)
packages/bridge-extension/icons/icon-{16,32,48,128}.png 16 to 128 full-bleed, plate shape read from harness/public/icon-512.png fraction: 0.52 (~66x84 at 128)
packages/landing/assets/og.png 1200x630 full-bleed fraction: 0.68 on height basis (~337x428)
packages/harness/src/assets/flupcode-logo.png, packages/landing/assets/flupcode-logo.png 256 / 320 transparent (no plate) artwork fit 0.90

Transparent logos (flupcode-logo.png) fit the whole artwork inside the canvas. Keep these values when the logo changes so every build mounts the same icon.

Caveat: icon.png reads its own plate shape, so a padded output feeds back into the next run — restore it from git before regenerating if the plate geometry ever drifts.