Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
75 changes: 75 additions & 0 deletions .github/workflows/prepare-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
name: Prepare release

on:
workflow_dispatch:
inputs:
version:
description: 'New stable version (for example, 3.0.1)'
required: true
title:
description: 'Release title'
required: false
description:
description: 'Short description for What’s New'
required: false
announce:
description: 'Show What’s New automatically after updating'
type: boolean
default: false

permissions:
contents: read

concurrency:
group: prepare-release
cancel-in-progress: false

jobs:
prepare:
runs-on: ubuntu-latest
steps:
- uses: actions/create-github-app-token@v2
id: app
with:
app-id: ${{ vars.RELEASE_APP_ID }}
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
owner: ${{ github.repository_owner }}
repositories: showcode
permission-contents: write
permission-pull-requests: write
- uses: actions/checkout@v5
with:
ref: master
fetch-depth: 0
token: ${{ steps.app.outputs.token }}
- uses: actions/setup-node@v5
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci
- name: Prepare notes and package versions
run: |
npm run release:prepare
npm run release:check
env:
RELEASE_VERSION: ${{ inputs.version }}
RELEASE_TITLE: ${{ inputs.title }}
RELEASE_DESCRIPTION: ${{ inputs.description }}
RELEASE_ANNOUNCE: ${{ inputs.announce }}
- name: Open release pull request
env:
GH_TOKEN: ${{ steps.app.outputs.token }}
RELEASE_VERSION: ${{ inputs.version }}
run: |
git config user.name 'Showcode Release Bot'
git config user.email 'release-bot@users.noreply.github.com'
git switch -c "release/v$RELEASE_VERSION"
git add package.json package-lock.json app/content/releases
git commit -m "Prepare Showcode $RELEASE_VERSION"
git push origin "HEAD:release/v$RELEASE_VERSION"
cat > "$RUNNER_TEMP/release-pr.md" <<'NOTES'
Review the release notes in this pull request and edit them into user-facing language before merging. The initial bullets come from commits since the previous release.

Merging this PR will sync the approved Showcode commit to the desktop repository and build a draft release. Publishing remains a separate, manual step after testing the installers.
NOTES
gh pr create --base master --head "release/v$RELEASE_VERSION" --title "Release Showcode $RELEASE_VERSION" --body-file "$RUNNER_TEMP/release-pr.md"
29 changes: 29 additions & 0 deletions .github/workflows/release-desktop.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
name: Queue desktop release

on:
pull_request:
types: [closed]
branches: [master]

permissions:
contents: read

jobs:
dispatch:
if: github.event.pull_request.merged && github.event.pull_request.head.repo.full_name == github.repository && startsWith(github.event.pull_request.head.ref, 'release/v')
runs-on: ubuntu-latest
steps:
- uses: actions/create-github-app-token@v2
id: app
with:
app-id: ${{ vars.RELEASE_APP_ID }}
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
owner: ${{ github.repository_owner }}
repositories: showcode-app
permission-actions: write
- name: Build the approved renderer commit
env:
GH_TOKEN: ${{ steps.app.outputs.token }}
RENDERER_REF: ${{ github.event.pull_request.merge_commit_sha }}
OWNER: ${{ github.repository_owner }}
run: gh workflow run build.yml --repo "$OWNER/showcode-app" --ref master -f renderer_ref="$RENDERER_REF"
5 changes: 5 additions & 0 deletions .github/workflows/run-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@ jobs:
- name: Prepare Nuxt
run: npx nuxi prepare

- name: Validate Release Notes
run: |
npm run release:check
npm run test:releases

- name: Run Tests
run: npx vitest run

Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ https://showcode.app/download

## Local Installation

For release preparation, desktop builds, and the required GitHub configuration, see the [release guide](docs/releases.md).

1. Clone the git repo
2. Run `npm install`
2. Run `NODE_OPTIONS=--openssl-legacy-provider npm run dev`
Expand Down
4 changes: 3 additions & 1 deletion app/components/ModalChangelog.vue
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,8 @@ function parseChangelog(raw) {

onMounted(async () => {
const md = await import('@/content/changelog.md?raw');
entries.value = parseChangelog(md.default);
const { default: releases } = await import('@/content/releases');
const { releaseChangelog } = await import('@/utils/releaseNotes');
entries.value = parseChangelog(`${releaseChangelog(releases)}\n\n---\n\n${md.default}`);
});
</script>
25 changes: 0 additions & 25 deletions app/content/changelog.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,3 @@
## November 3, 2026 — Version 3.0.0

**Added**

- Added floating editor and preview toolbars with language, editor settings, copy, export, fit, and zoom controls
- Added a collapsible inspector with Style, Themes, Backdrop, and Scenes controls
- Added visual choices for workspace layout and window position
- Added desktop release announcements that appear once after an update and can be reopened from Help
- Added native desktop menus, file dialogs, image export, and clipboard support

**Changed**

- Refreshed the window structure, project tabs, settings popovers, and form controls
- Added smooth editor reordering while preserving resizable dividers
- Expanded canvas zoom with typed percentages and additional presets
- Aligned hover and keyboard focus styling across the application
- Simplified the loading screen to the logo and loading indicator

**Fixed**

- Fixed clipping around rounded changelog cards
- Fixed toolbar overflow and spacing in smaller windows

---

## August 17, 2026 — Version 2.8

**Added**
Expand Down
26 changes: 10 additions & 16 deletions app/content/releases.js
Original file line number Diff line number Diff line change
@@ -1,17 +1,11 @@
import workspaceRefresh from './releases/workspace-refresh.md?raw';
import workspacePreview from '@/assets/images/workspace-refresh.svg';
import { parseRelease, sortReleases } from '@/utils/releaseNotes';

// Keep the newest release first. Set announce to false for maintenance releases.
export default [
{
id: 'workspace-refresh',
version: '3.0.0',
date: 'November 3, 2026',
title: 'A refreshed workspace',
description: 'More room for your code, with your tools close at hand.',
announce: true,
image: workspacePreview,
imageAlt: 'The refreshed workspace with floating toolbars and a collapsible inspector.',
content: workspaceRefresh,
},
];
const sources = import.meta.glob('./releases/*.md', {
query: '?raw',
import: 'default',
eager: true,
});

export default sortReleases(
Object.entries(sources).map(([filename, source]) => parseRelease(source, filename))
);
32 changes: 26 additions & 6 deletions app/content/releases/workspace-refresh.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,31 @@
## Floating toolbars
---
id: workspace-refresh
version: 3.0.0
date: 2026-11-03
title: A refreshed workspace
description: More room for your code, with your tools close at hand.
announce: true
image: /images/releases/workspace-refresh.svg
imageAlt: The refreshed workspace with floating toolbars and a collapsible inspector.
---

Language, editor settings, copy, export, and zoom now sit in compact toolbars, giving your code and preview more room.
**Added**

## A collapsible inspector
- Added floating editor and preview toolbars with language, editor settings, copy, export, fit, and zoom controls
- Added a collapsible inspector with Style, Themes, Backdrop, and Scenes controls
- Added visual choices for workspace layout and window position
- Added desktop release announcements that appear once after an update and can be reopened from Help
- Added native desktop menus, file dialogs, image export, and clipboard support

Switch between Style, Themes, Backdrop, and Scenes from the bottom of the inspector. Hide it when you want more space for your canvas.
**Changed**

## Smoother workspace controls
- Refreshed the window structure, project tabs, settings popovers, and form controls
- Added smooth editor reordering while preserving resizable dividers
- Expanded canvas zoom with typed percentages and additional presets
- Aligned hover and keyboard focus styling across the application
- Simplified the loading screen to the logo and loading indicator

Reorder editors with a smooth transition, choose your layout visually, and type a zoom percentage to get a closer look.
**Fixed**

- Fixed clipping around rounded changelog cards
- Fixed toolbar overflow and spacing in smaller windows
74 changes: 74 additions & 0 deletions app/utils/releaseNotes.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
import { parse } from 'yaml';

export function compareReleaseVersions(left, right) {
const a = left.split('.').map(Number);
const b = right.split('.').map(Number);
return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
}

export function assertReleaseVersion(version) {
if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version)) {
throw new Error('Use a stable version such as 3.0.1.');
}
}

export function parseRelease(source, filename = 'Release notes') {
const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
if (!match) throw new Error(`${filename}: YAML front matter is required.`);
const metadata = parse(match[1]);
const content = match[2].trim();

for (const field of ['id', 'version', 'date', 'title', 'description']) {
if (typeof metadata?.[field] !== 'string' || !metadata[field].trim()) {
throw new Error(`${filename}: ${field} is required.`);
}
}

assertReleaseVersion(metadata.version);
if (!/^[a-z0-9-]+$/.test(metadata.id)) throw new Error(`${filename}: Invalid release ID.`);
if (
!/^\d{4}-\d{2}-\d{2}$/.test(metadata.date) ||
!Number.isFinite(Date.parse(metadata.date)) ||
new Date(metadata.date).toISOString().slice(0, 10) !== metadata.date
) {
throw new Error(`${filename}: Use a valid YYYY-MM-DD date.`);
}
if (typeof metadata.announce !== 'boolean') {
throw new Error(`${filename}: announce must be true or false.`);
}
if (!content) throw new Error(`${filename}: Release notes cannot be empty.`);
if (
metadata.image &&
(typeof metadata.image !== 'string' ||
!metadata.image.startsWith('/images/') ||
metadata.image.split('/').includes('..') ||
!metadata.imageAlt)
) {
throw new Error(`${filename}: Images need a /images/ path and imageAlt.`);
}

return {
...metadata,
publishedAt: metadata.date,
date: new Intl.DateTimeFormat('en-US', {
dateStyle: 'long',
timeZone: 'UTC',
}).format(new Date(metadata.date)),
content,
};
}

export function sortReleases(releases) {
for (const field of ['id', 'version']) {
if (new Set(releases.map((release) => release[field])).size !== releases.length) {
throw new Error(`Release ${field}s must be unique.`);
}
}
return releases.sort((a, b) => compareReleaseVersions(b.version, a.version));
}

export function releaseChangelog(releases) {
return releases
.map((release) => `## ${release.date} — Version ${release.version}\n\n${release.content}`)
.join('\n\n---\n\n');
}
87 changes: 87 additions & 0 deletions docs/releases.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Releasing Showcode

Release metadata and notes live together in `app/content/releases/*.md`. These entries supply the in-app What's New dialog, the recent changelog, and the desktop GitHub release. `app/content/changelog.md` contains only the older, pre-3.0 history.

## Normal release flow

1. Merge feature and fix PRs into `master` normally.
2. In **Showcode → Actions → Prepare release**, choose a new stable version such as `3.0.1`. Add a title and short description. Enable **announce** for releases that should open What's New automatically; leave it off for maintenance updates.
3. The action opens `release/v3.0.1`. Review the Markdown entry and replace the generated commit bullets with useful release notes. Add an optional image if appropriate.
4. Merge the release PR after checks pass. This queues the desktop build with the exact merged Showcode SHA. Later web commits cannot slip into that build.
5. Wait for **showcode-app → Build desktop release**. It synchronizes the submodule and desktop version, records a commit/tag, builds all platforms, verifies installers and updater manifests, and creates a draft GitHub release.
6. Download and test an installer from the draft, then click **Publish release**. The tested files are the files users receive; publishing does not rebuild them.

Releases are never automatically published to users. Ordinary merges do not queue desktop releases; only merged branches whose names start with `release/v` do.

## Release entry

```markdown
---
id: 3-0-1
version: 3.0.1
date: 2026-11-04
title: Smoother editing
description: Small improvements to your workspace.
announce: false
image: /images/releases/3.0.1.png
imageAlt: The improved Showcode editor
---

**Changed**

- Improved the editor opening animation.

**Fixed**

- Fixed an issue with …
```

Images are optional. Place them in `public/images/releases/`, use the `/images/releases/...` URL, and include `imageAlt`. Keep `id` stable after shipping: desktop installations use it to remember which announcements they have seen. Use **Added**, **Changed**, **Fixed**, or **Removed** sections with bullet points so the changelog can display them.

The current version is checked against the newest entry. A release must use a new, increasing `major.minor.patch` version. This workflow currently publishes stable releases only.

To prepare a release locally instead of using Actions:

```sh
npm run release:prepare -- 3.0.1
npm run release:check
npm run test:releases
```

This edits files only. It does not commit, push, create a PR, or start a release. Open a PR from `release/v3.0.1` to use the automated handoff.

## GitHub configuration

Create a GitHub App (for example, **Showcode Release Bot**) and install it only on `stevebauman/showcode` and `stevebauman/showcode-app`. Webhooks can be disabled; the workflows call GitHub directly.

Give the App these repository permissions:

| Permission | Access | Purpose |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| Contents | Read and write | Create release branches, synchronize the desktop submodule/version, and create tags |
| Pull requests | Read and write | Open release PRs in Showcode |
| Actions | Read and write | Dispatch the desktop build workflow |
| Metadata | Read | GitHub's required repository access |

In **both repositories**, configure:

| Kind | Name | Value |
| ---------------- | ------------------------- | -------------------------------------- |
| Actions variable | `RELEASE_APP_ID` | The GitHub App ID |
| Actions secret | `RELEASE_APP_PRIVATE_KEY` | The complete generated PEM private key |

Each workflow requests only the repository and permissions it needs. The regular `GITHUB_TOKEN` handles draft release uploads inside showcode-app.

Keep the existing Apple signing secrets in showcode-app: `APPLE_ID`, `APPLE_ID_PASSWORD`, `APPLE_TEAM_ID`, `CSC_LINK`, and `CSC_KEY_PASSWORD`. `CSC_LINK` must remain the base64-encoded P12 certificate expected by the build workflow.

Allow the App to push the mechanical release commit to **showcode-app/master** and create its `v*` tags. If branch/tag rules require PRs, signatures, or status checks before every push, grant this App a targeted bypass for the desktop release path. Showcode itself still uses reviewed PRs and needs no master bypass. Also permit the actions used in these workflows under the repository's Actions policy.

## First-time rollout and recovery

Merge/configure **showcode-app first**, then Showcode. The first configuration PR should use an ordinary branch name, not `release/v…`; it does not represent a new product release. Keep the current 3.0.0 version until preparing the next release.

If dispatch fails, re-run **Queue desktop release** after correcting the App configuration. If a platform build fails, choose **Re-run failed jobs** on the existing desktop workflow run. This retains the approved commit and successful platform artifacts.

For a full rebuild, manually run **Build desktop release** with the original approved Showcode SHA. A published version cannot be rebuilt or overwritten; prepare a new version instead. If desktop master has advanced since the failed run, prefer re-running its failed jobs rather than starting from a different master snapshot.

Draft creation and uploading happen only after all platform jobs succeed. If uploading fails, retry the failed job: existing draft assets are replaced, but a published release is never modified.
Loading
Loading