From e3b0ba10d0eed8a8169db22e0825fba97bf1b0c4 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:22:12 +0000 Subject: [PATCH 01/10] feat(ci): add Conventional Commit desktop release planner Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- scripts/plan-desktop-release.mjs | 129 +++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 scripts/plan-desktop-release.mjs diff --git a/scripts/plan-desktop-release.mjs b/scripts/plan-desktop-release.mjs new file mode 100644 index 0000000..2ad68e8 --- /dev/null +++ b/scripts/plan-desktop-release.mjs @@ -0,0 +1,129 @@ +#!/usr/bin/env node +// SPDX-License-Identifier: GPL-3.0-or-later +// Determine a stable desktop release using Conventional Commits since the +// preceding release. No tags, version files or releases are written here. +import { execFileSync } from 'node:child_process'; +import { appendFileSync, readFileSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { assertReleaseTag, readDesktopVersion } from './desktop-version.mjs'; + +const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const STABLE_TAG = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/; +const MANUAL_TAG = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/; +const LEVEL = { none: 0, patch: 1, minor: 2, major: 3 }; + +export function parseStableTag(tag) { + const match = STABLE_TAG.exec(tag); + return match ? match.slice(1).map(Number) : null; +} +export function latestStableTag(tags) { + const stable = tags.map(tag => ({ tag, parts: parseStableTag(tag) })).filter(item => item.parts); + stable.sort((a, b) => { + for (let i = 0; i < 3; i += 1) { + if (a.parts[i] !== b.parts[i]) return b.parts[i] - a.parts[i]; + } + return 0; + }); + return stable[0]?.tag ?? null; +} +export function conventionalChange(message) { + const header = message.split(/\r?\n/, 1)[0].trim(); + const match = /^([a-z][a-z0-9-]*)(?:\([a-zA-Z0-9._/-]+\))?(!)?:\s+(.+)$/.exec(header); + if (!match) return { level: 'none', header }; + const breaking = Boolean(match[2]) || /^BREAKING(?: CHANGE|-CHANGE):\s*\S/im.test(message); + const level = breaking ? 'major' : match[1] === 'feat' ? 'minor' : + ['fix', 'perf', 'revert'].includes(match[1]) ? 'patch' : 'none'; + return { level, header, type: match[1] }; +} +export function nextVersion(version, level) { + const parts = parseStableTag('v' + version); + if (!parts) throw new Error('Invalid previous stable release version: ' + version); + if (level === 'major') return (parts[0] + 1) + '.0.0'; + if (level === 'minor') return parts[0] + '.' + (parts[1] + 1) + '.0'; + if (level === 'patch') return parts[0] + '.' + parts[1] + '.' + (parts[2] + 1); + if (level === 'none') return version; + throw new Error('Unsupported release level'); +} +export function releaseDecision(previousTag, messages) { + const previous = parseStableTag(previousTag); + if (!previous) throw new Error('A previous stable vX.Y.Z tag is required'); + const relevant = messages.map(conventionalChange).filter(change => change.level !== 'none'); + const level = relevant.reduce((maximum, change) => + LEVEL[change.level] > LEVEL[maximum] ? change.level : maximum, 'none'); + const version = nextVersion(previous.join('.'), level); + return { publish: level !== 'none', version, tag: level === 'none' ? '' : 'v' + version, level, changes: relevant }; +} +export function parseGitMessages(output) { + return output.split('\0').map(message => message.trim()).filter(Boolean); +} +function git(...args) { + return execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }).trim(); +} +export function planFromGit() { + const previousTag = latestStableTag(git('tag', '--list', 'v*').split(/\r?\n/).filter(Boolean)); + if (!previousTag) throw new Error('Cannot automate releases without an existing stable tag'); + const baseSha = git('merge-base', previousTag, 'HEAD'); + const tagSha = git('rev-parse', previousTag + '^{commit}'); + const parents = git('rev-list', '--parents', '-n', '1', previousTag).split(/\s+/); + // Auto-release tags may point to a version-only commit whose parent is + // main. Do not include that synthetic release commit in the next range. + if (baseSha !== tagSha && (parents.length !== 2 || baseSha !== parents[1])) { + throw new Error('Latest release tag does not belong to this main branch history'); + } + const messages = parseGitMessages(git('log', '--format=%B%x00', baseSha + '..HEAD')); + return { ...releaseDecision(previousTag, messages), baseSha, previousTag }; +} +export function releaseNotes(template, messages, tag, previousTag) { + const entries = messages.map(conventionalChange).filter(change => change.level !== 'none'); + const sections = [ + ['Mudanças incompatíveis', entries.filter(change => change.level === 'major')], + ['Funcionalidades', entries.filter(change => change.level === 'minor')], + ['Correções e desempenho', entries.filter(change => change.level === 'patch')], + ].filter(([, items]) => items.length).map(([title, items]) => + '### ' + title + '\n\n' + items.map(item => '- ' + item.header).join('\n')); + return template.trim() + '\n\n## ' + tag + ' — alterações desde ' + previousTag + '\n\n' + sections.join('\n\n') + '\n'; +} +function run() { + const [mode, ...args] = process.argv.slice(2); + if (mode === '--notes') { + if (args.length !== 3) throw new Error('Usage: --notes '); + const [baseSha, headSha, tag] = args; + if (!parseStableTag(tag) || !/^[0-9a-f]{40}$/.test(baseSha) || !/^[0-9a-f]{40}$/.test(headSha)) { + throw new Error('Invalid release notes inputs'); + } + const messages = parseGitMessages(git('log', '--format=%B%x00', baseSha + '..' + headSha)); + const previousTag = latestStableTag(git('tag', '--list', 'v*').split(/\r?\n/).filter(Boolean)); + const template = readFileSync(join(ROOT, '.github', 'RELEASE_NOTES.md'), 'utf8'); + process.stdout.write(releaseNotes(template, messages, tag, previousTag)); + return; + } + if (mode !== '--github-output') throw new Error('Usage: --github-output | --notes '); + const { GITHUB_EVENT_NAME: event, GITHUB_REF_TYPE: refType, GITHUB_REF_NAME: refName, + GITHUB_REF: ref, GITHUB_OUTPUT: output, RELEASE_TAG_INPUT: requestedTag } = process.env; + if (!output) throw new Error('GITHUB_OUTPUT is required'); + const current = readDesktopVersion(); + let result; + if (event === 'push' && ref === 'refs/heads/main') { + result = planFromGit(); + if (parseStableTag('v' + current) && parseStableTag('v' + result.version) && + latestStableTag(['v' + current, 'v' + result.version]) === 'v' + current && + current !== result.version) { + throw new Error('Desktop package version ' + current + ' is ahead of calculated release ' + result.version); + } + } else if ((event === 'push' && refType === 'tag') || + (event === 'workflow_dispatch' && requestedTag)) { + const tag = event === 'workflow_dispatch' ? requestedTag : refName; + if (!MANUAL_TAG.test(tag)) throw new Error('Invalid desktop release tag'); + assertReleaseTag(current, 'tag', tag); + result = { publish: true, tag, version: current, baseSha: '', previousTag: '' }; + } else { + result = { publish: false, tag: '', version: current, baseSha: '', previousTag: '' }; + } + appendFileSync(output, 'publish=' + result.publish + '\nversion=' + result.version + + '\ntag=' + result.tag + '\nbase_sha=' + result.baseSha + '\nprevious_tag=' + result.previousTag + '\n'); + console.log(result.publish ? 'Planned desktop release ' + result.tag : 'No new desktop release required'); +} +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + try { run(); } catch (error) { console.error(error.message); process.exitCode = 1; } +} From 3f2310952398caf57afbb05daa48691575ffaf8e Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:22:49 +0000 Subject: [PATCH 02/10] test(ci): cover SemVer release planning and Git sidecar tags Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- scripts/plan-desktop-release.mjs | 2 +- scripts/plan-desktop-release.test.mjs | 101 ++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 scripts/plan-desktop-release.test.mjs diff --git a/scripts/plan-desktop-release.mjs b/scripts/plan-desktop-release.mjs index 2ad68e8..853fe30 100644 --- a/scripts/plan-desktop-release.mjs +++ b/scripts/plan-desktop-release.mjs @@ -106,7 +106,7 @@ function run() { let result; if (event === 'push' && ref === 'refs/heads/main') { result = planFromGit(); - if (parseStableTag('v' + current) && parseStableTag('v' + result.version) && + if (result.publish && parseStableTag('v' + current) && parseStableTag('v' + result.version) && latestStableTag(['v' + current, 'v' + result.version]) === 'v' + current && current !== result.version) { throw new Error('Desktop package version ' + current + ' is ahead of calculated release ' + result.version); diff --git a/scripts/plan-desktop-release.test.mjs b/scripts/plan-desktop-release.test.mjs new file mode 100644 index 0000000..46f0f4c --- /dev/null +++ b/scripts/plan-desktop-release.test.mjs @@ -0,0 +1,101 @@ +// SPDX-License-Identifier: GPL-3.0-or-later +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, rmSync } from 'node:fs'; +import { execFileSync } from 'node:child_process'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { conventionalChange, latestStableTag, nextVersion, parseGitMessages, releaseDecision, releaseNotes } from './plan-desktop-release.mjs'; + +test('highest stable SemVer tag excludes prereleases and invalid tags', () => { + assert.equal(latestStableTag(['v0.4.9', 'v0.10.0', 'v1.0.0-rc.1', 'v0.9.10', 'anything']), 'v0.10.0'); + assert.equal(latestStableTag(['v0.4.0-beta.1', 'unrelated']), null); +}); +test('features, fixes, performance, breaking changes and nonreleasing commits', () => { + assert.equal(conventionalChange('feat(ui): new panel').level, 'minor'); + assert.equal(conventionalChange('fix: bad cache').level, 'patch'); + assert.equal(conventionalChange('perf: faster startup').level, 'patch'); + assert.equal(conventionalChange('refactor!: remove legacy API').level, 'major'); + assert.equal(conventionalChange('feat(api): update\n\nBREAKING CHANGE: incompatible').level, 'major'); + for (const message of ['docs: README', 'test: coverage', 'chore(release): v0.4.1', 'Merge pull request #52']) { + assert.equal(conventionalChange(message).level, 'none'); + } +}); +test('highest bump prevails; docs-only changes do not release', () => { + assert.equal(releaseDecision('v0.4.1', ['docs: usage', 'test: browser']).publish, false); + assert.equal(releaseDecision('v0.4.1', ['fix: bug']).tag, 'v0.4.2'); + assert.equal(releaseDecision('v0.4.1', ['fix: bug', 'feat: new']).tag, 'v0.5.0'); + assert.equal(releaseDecision('v0.4.1', ['feat!: change old API']).tag, 'v1.0.0'); +}); +test('invalid baselines fail, and versions follow SemVer', () => { + assert.throws(() => releaseDecision('v0.4.0-rc.1', ['feat: new']), /previous stable/); + assert.equal(nextVersion('0.9.11', 'minor'), '0.10.0'); +}); +test('NUL-delimited Git messages produce readable release notes', () => { + const messages = parseGitMessages('feat: first\n\nSigned-off-by: user\0fix: second\n\0chore: build\0'); + assert.equal(messages.length, 3); + const notes = releaseNotes('Safety notes.\n', messages, 'v0.5.0', 'v0.4.0'); + assert.match(notes, /Safety notes/); + assert.match(notes, /- feat: first/); + assert.match(notes, /- fix: second/); + assert.doesNotMatch(notes, /chore: build/); +}); +test('real Git: no release for docs-only merge; tagged release sidecar does not double release', () => { + const root = mkdtempSync(join(tmpdir(), 'kimai-release-git-')); + const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim(); + try { + mkdirSync(join(root, 'scripts')); + mkdirSync(join(root, 'nativephp', 'electron'), { recursive: true }); + copyFileSync(new URL('./plan-desktop-release.mjs', import.meta.url), join(root, 'scripts', 'plan-desktop-release.mjs')); + copyFileSync(new URL('./desktop-version.mjs', import.meta.url), join(root, 'scripts', 'desktop-version.mjs')); + const pkg = version => JSON.stringify({ name: 'automatic-kimai', version }); + const lock = version => JSON.stringify({ name: 'automatic-kimai', version, + packages: { '': { name: 'automatic-kimai', version } } }); + const file = name => join(root, 'nativephp', 'electron', name); + writeFileSync(file('package.json'), pkg('0.4.0')); + writeFileSync(file('package-lock.json'), lock('0.4.0')); + git('init', '-b', 'main'); + git('config', 'user.email', 'tester@example.test'); + git('config', 'user.name', 'Test'); + git('add', '.'); + git('commit', '-m', 'chore: initial release'); + git('tag', 'v0.4.0'); + // Source package may be ahead of the last tag without triggering a docs-only release. + writeFileSync(file('package.json'), pkg('0.4.1')); + writeFileSync(file('package-lock.json'), lock('0.4.1')); + git('add', '.'); + git('commit', '-m', 'docs: adjust download table'); + const output = join(root, 'outputs'); + const env = { ...process.env, GITHUB_EVENT_NAME: 'push', GITHUB_REF_TYPE: 'branch', + GITHUB_REF_NAME: 'main', GITHUB_REF: 'refs/heads/main', GITHUB_OUTPUT: output }; + const run = () => { + writeFileSync(output, ''); + return execFileSync('node', ['scripts/plan-desktop-release.mjs', '--github-output'], + { cwd: root, env, encoding: 'utf8' }); + }; + run(); + assert.match(readFileSync(output, 'utf8'), /publish=false/); + writeFileSync(join(root, 'feature.txt'), 'feature'); + git('add', '.'); + git('commit', '-m', 'feat: useful feature'); + const originalMain = git('rev-parse', 'HEAD'); + run(); + assert.match(readFileSync(output, 'utf8'), /tag=v0\.5\.0/); + git('checkout', '--detach', '-q'); + writeFileSync(file('package.json'), pkg('0.5.0')); + writeFileSync(file('package-lock.json'), lock('0.5.0')); + git('add', '.'); + git('commit', '-m', 'chore(release): v0.5.0'); + git('tag', 'v0.5.0'); + git('checkout', '-q', 'main'); + assert.equal(git('rev-parse', 'HEAD'), originalMain); + run(); + assert.match(readFileSync(output, 'utf8'), /publish=false/); + writeFileSync(join(root, 'fix.txt'), 'fix'); + git('add', '.'); + git('commit', '-m', 'fix: regression'); + run(); + assert.match(readFileSync(output, 'utf8'), /tag=v0\.5\.1/); + assert.match(readFileSync(output, 'utf8'), /publish=true/); + } finally { rmSync(root, { force: true, recursive: true }); } +}); From ff563d31835a11ed483dd4538fb72c16f3d10586 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:24:26 +0000 Subject: [PATCH 03/10] feat(ci): plan releases from main and stamp package versions Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .github/workflows/desktop-release.yml | 67 ++++++++++++++++++++++----- 1 file changed, 56 insertions(+), 11 deletions(-) diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml index dbb4cf0..1b8fa2e 100644 --- a/.github/workflows/desktop-release.yml +++ b/.github/workflows/desktop-release.yml @@ -13,19 +13,55 @@ on: - 'composer.*' - 'README.md' push: + branches: + - main tags: - 'v*' workflow_dispatch: + inputs: + release_tag: + description: 'Existing tag to rebuild and publish; leave empty for preview.' + required: false + type: string permissions: contents: read concurrency: - group: desktop-installers-${{ github.ref }} + group: desktop-installers-${{ github.event_name == 'pull_request' && github.ref || 'release-serialization' }} cancel-in-progress: false jobs: + plan: + name: Determine release from Conventional Commits + runs-on: ubuntu-24.04 + timeout-minutes: 10 + outputs: + publish: ${{ steps.plan.outputs.publish }} + version: ${{ steps.plan.outputs.version }} + tag: ${{ steps.plan.outputs.tag }} + base_sha: ${{ steps.plan.outputs.base_sha }} + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + fetch-depth: 0 + ref: ${{ inputs.release_tag || github.sha }} + - uses: actions/setup-node@v4 + with: + node-version: '22' + - name: Plan release or preview + id: plan + env: + RELEASE_TAG_INPUT: ${{ inputs.release_tag || '' }} + run: node scripts/plan-desktop-release.mjs --github-output + packages: + needs: plan + if: >- + needs.plan.outputs.publish == 'true' || + github.event_name == 'pull_request' || + github.event_name == 'workflow_dispatch' name: ${{ matrix.target }} / ${{ matrix.arch }} runs-on: ${{ matrix.runner }} timeout-minutes: 80 @@ -48,20 +84,22 @@ jobs: env: CI: 'true' NODE_ENV: 'development' + NATIVEPHP_APP_VERSION: ${{ needs.plan.outputs.version }} CSC_IDENTITY_AUTO_DISCOVERY: 'false' # No signing credentials are available to untrusted pull requests. - CSC_LINK: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_CSC_LINK || '' }} - CSC_KEY_PASSWORD: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_CSC_KEY_PASSWORD || '' }} - NATIVEPHP_APPLE_ID: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_APPLE_ID || '' }} - NATIVEPHP_APPLE_ID_PASS: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_APPLE_ID_PASS || '' }} - NATIVEPHP_APPLE_TEAM_ID: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_APPLE_TEAM_ID || '' }} - WIN_CSC_LINK: ${{ github.ref_type == 'tag' && matrix.target == 'win' && secrets.WIN_CSC_LINK || '' }} - WIN_CSC_KEY_PASSWORD: ${{ github.ref_type == 'tag' && matrix.target == 'win' && secrets.WIN_CSC_KEY_PASSWORD || '' }} + CSC_LINK: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_CSC_LINK || '' }} + CSC_KEY_PASSWORD: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_CSC_KEY_PASSWORD || '' }} + NATIVEPHP_APPLE_ID: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_APPLE_ID || '' }} + NATIVEPHP_APPLE_ID_PASS: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_APPLE_ID_PASS || '' }} + NATIVEPHP_APPLE_TEAM_ID: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_APPLE_TEAM_ID || '' }} + WIN_CSC_LINK: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'win' && secrets.WIN_CSC_LINK || '' }} + WIN_CSC_KEY_PASSWORD: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'win' && secrets.WIN_CSC_KEY_PASSWORD || '' }} steps: - uses: actions/checkout@v4 with: persist-credentials: false + ref: ${{ inputs.release_tag || github.sha }} - uses: shivammathur/setup-php@v2 with: php-version: '8.4' @@ -73,12 +111,19 @@ jobs: node-version: '22' cache: npm cache-dependency-path: nativephp/electron/package-lock.json - - name: Resolve and validate desktop version + - name: Stamp planned version into the packaging workspace shell: bash - run: node scripts/desktop-version.mjs --github-env + env: + RELEASE_VERSION: ${{ needs.plan.outputs.version }} + run: | + set -euo pipefail + if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then + (cd nativephp/electron && npm version "$RELEASE_VERSION" --no-git-tag-version --ignore-scripts --allow-same-version) + fi + node scripts/desktop-version.mjs --github-env - name: Test versioning and release preparation without publishing shell: bash - run: node --test scripts/desktop-version.test.mjs scripts/create-update-manifests.test.mjs scripts/prepare-desktop-release.test.mjs + run: node --test scripts/desktop-version.test.mjs scripts/create-update-manifests.test.mjs scripts/prepare-desktop-release.test.mjs scripts/plan-desktop-release.test.mjs - name: Install PHP dependencies shell: bash run: | From 30baa8dc4c2879c7f302380fdd139d73ca2d35b4 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:24:44 +0000 Subject: [PATCH 04/10] feat(ci): tag versioned builds and publish releases after successful checks Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .github/workflows/desktop-release.yml | 77 ++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 12 deletions(-) diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml index 1b8fa2e..2f31129 100644 --- a/.github/workflows/desktop-release.yml +++ b/.github/workflows/desktop-release.yml @@ -209,15 +209,17 @@ jobs: retention-days: 7 publish: - if: startsWith(github.ref, 'refs/tags/v') - needs: packages + if: needs.plan.outputs.publish == 'true' + needs: [plan, packages] runs-on: ubuntu-24.04 permissions: contents: write steps: - uses: actions/checkout@v4 with: - persist-credentials: false + persist-credentials: true + fetch-depth: 0 + ref: ${{ inputs.release_tag || github.sha }} - uses: actions/setup-node@v4 with: node-version: '22' @@ -226,23 +228,74 @@ jobs: pattern: installer-* path: release-output merge-multiple: true + - name: Stamp and validate release version + shell: bash + env: + RELEASE_VERSION: ${{ needs.plan.outputs.version }} + run: | + set -euo pipefail + if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then + (cd nativephp/electron && npm version "$RELEASE_VERSION" --no-git-tag-version --ignore-scripts --allow-same-version) + fi + node scripts/desktop-version.mjs - name: Prepare and test release assets shell: bash - run: node scripts/prepare-desktop-release.mjs release-output "$GITHUB_REF_NAME" - - name: Publish public desktop release + env: + RELEASE_TAG: ${{ needs.plan.outputs.tag }} + run: node scripts/prepare-desktop-release.mjs release-output "$RELEASE_TAG" + - name: Prepare release notes + shell: bash + env: + RELEASE_TAG: ${{ needs.plan.outputs.tag }} + BASE_SHA: ${{ needs.plan.outputs.base_sha }} + run: | + set -euo pipefail + cp .github/RELEASE_NOTES.md release-notes.md + if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then + node scripts/plan-desktop-release.mjs --notes "$BASE_SHA" "$GITHUB_SHA" "$RELEASE_TAG" > release-notes.md + fi + - name: Tag the versioned sources after successful builds + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + shell: bash + env: + RELEASE_TAG: ${{ needs.plan.outputs.tag }} + run: | + set -euo pipefail + git checkout --detach "$GITHUB_SHA" + if ! git diff --quiet -- nativephp/electron/package.json nativephp/electron/package-lock.json; then + git add -- nativephp/electron/package.json nativephp/electron/package-lock.json + git -c user.name='github-actions[bot]' \ + -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \ + commit -s -m "chore(release): ${RELEASE_TAG}" + fi + test "$(node scripts/desktop-version.mjs)" = "${RELEASE_TAG#v}" + if git show-ref --verify --quiet "refs/tags/${RELEASE_TAG}"; then + echo 'Release tag already exists; refusing to overwrite it' >&2 + exit 1 + fi + git tag "$RELEASE_TAG" + git push origin "refs/tags/${RELEASE_TAG}" + - name: Publish verified assets and finalize release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} GH_REPO: ${{ github.repository }} + RELEASE_TAG: ${{ needs.plan.outputs.tag }} shell: bash run: | set -euo pipefail + if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then + echo 'Release already exists; refusing duplicate publication' >&2 + exit 1 + fi mapfile -d '' files < <(find release-output -maxdepth 1 -type f -print0) - if [[ "$GITHUB_REF_NAME" == *-* ]]; then - gh release create "$GITHUB_REF_NAME" "${files[@]}" --target "$GITHUB_SHA" \ - --title "Automatic Kimai $GITHUB_REF_NAME (prévia)" \ - --prerelease --notes-file .github/RELEASE_NOTES.md + if [[ "$RELEASE_TAG" == *-* ]]; then + gh release create "$RELEASE_TAG" "${files[@]}" --verify-tag --draft \ + --title "Automatic Kimai $RELEASE_TAG (prévia)" \ + --prerelease --notes-file release-notes.md + gh release edit "$RELEASE_TAG" --draft=false --latest=false else - gh release create "$GITHUB_REF_NAME" "${files[@]}" --target "$GITHUB_SHA" \ - --title "Automatic Kimai $GITHUB_REF_NAME" \ - --latest --notes-file .github/RELEASE_NOTES.md + gh release create "$RELEASE_TAG" "${files[@]}" --verify-tag --draft \ + --title "Automatic Kimai $RELEASE_TAG" \ + --notes-file release-notes.md + gh release edit "$RELEASE_TAG" --draft=false --latest fi From 8e48b10eb02851c037e030fe7a90430cb7ae21ba Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:25:17 +0000 Subject: [PATCH 05/10] docs(ci): document automatic releases and require Conventional Commits Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .github/workflows/conventional-commits.yml | 20 +++++++ .github/workflows/php-ci.yml | 2 +- docs/DISTRIBUTION.md | 65 ++++++++++++++-------- scripts/desktop-version.mjs | 2 +- 4 files changed, 64 insertions(+), 25 deletions(-) create mode 100644 .github/workflows/conventional-commits.yml diff --git a/.github/workflows/conventional-commits.yml b/.github/workflows/conventional-commits.yml new file mode 100644 index 0000000..2e1aafa --- /dev/null +++ b/.github/workflows/conventional-commits.yml @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: GPL-3.0-or-later +# Same pinned Conventional Commits validator used by LibreSign. +name: Conventional commits +on: + pull_request: + types: [opened, ready_for_review, reopened, synchronize] + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + - uses: webiny/action-conventional-commits@7f91b1595ca1951cdb671ddc9f07a49081ec5b69 # v1.4.2 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/php-ci.yml b/.github/workflows/php-ci.yml index f289a8d..7c3bd15 100644 --- a/.github/workflows/php-ci.yml +++ b/.github/workflows/php-ci.yml @@ -73,7 +73,7 @@ jobs: - name: Check build dependency security and compatibility run: node --test build/dependency-compat.test.mjs - name: Test desktop update flow and metadata - run: node --test src/main/updates.test.mjs ../../scripts/create-update-manifests.test.mjs ../../scripts/desktop-version.test.mjs ../../scripts/prepare-desktop-release.test.mjs + run: node --test src/main/updates.test.mjs ../../scripts/create-update-manifests.test.mjs ../../scripts/desktop-version.test.mjs ../../scripts/prepare-desktop-release.test.mjs ../../scripts/plan-desktop-release.test.mjs - name: Validate canonical desktop version and lockfile run: node ../../scripts/desktop-version.mjs - name: Compile NativePHP Electron plugin (required for #plugin import) diff --git a/docs/DISTRIBUTION.md b/docs/DISTRIBUTION.md index 9ee8a4f..fd0e8ef 100644 --- a/docs/DISTRIBUTION.md +++ b/docs/DISTRIBUTION.md @@ -12,13 +12,23 @@ project at the repository root; NativePHP/Electron lives under - macOS Intel x64 → `.dmg` - macOS Apple Silicon arm64 → `.dmg` -The workflow runs on PRs affecting packaging and on signed release tags -matching the version in `nativephp/electron/package.json` (the single canonical -application version). npm maintains `package-lock.json`, which is checked for -consistency. CI resolves `NATIVEPHP_APP_VERSION` from this package; do not set -release versions in the workflow or PHP configuration. A tag triggers -GitHub release upload only after all four package jobs succeed and their -installer checks verify the files and embedded PHP runtime. +The workflow builds pull-request previews and evaluates each push to `main` +for a stable release based on Conventional Commits since the previous stable +tag. `fix:` and `perf:` mean PATCH, `feat:` means MINOR; the `!` marker +or a `BREAKING CHANGE:` footer means MAJOR. The highest increment wins. +`docs:`, `test:`, `chore:` and non-conventional commits alone do not +cause a release. A documentation-only merge skips installers entirely. + +The version is calculated from Git history, not hardcoded in the workflow. +The release build updates `nativephp/electron/package.json` and its +npm-generated lockfile in the packaging workspace. After all four OS jobs +and package validation pass, it tags the exact sources with updated version +metadata. This version-only release commit is attached to the tag, **not** +merged into `main`; the application code remains identical to the merged +commit. Future release planning compares `main` against the previous +release tag or its main parent, preventing duplicate releases. The package +version is canonical for a checkout or installed release; no independent +manually managed version belongs in PHP or GitHub Actions. PR builds produce temporary workflow artifacts only. A tag containing a prerelease suffix is labeled **pre-release**; normal version tags are @@ -87,19 +97,28 @@ Never describe a successful cross-platform *build* as a verified user installati ## Releasing -1. Set the intended version with `npm version --no-git-tag-version` - inside `nativephp/electron/`; commit both npm metadata files together. - `node scripts/desktop-version.mjs` validates their consistency. -2. Run the release preparation tests without a release: - `node --test scripts/desktop-version.test.mjs scripts/create-update-manifests.test.mjs scripts/prepare-desktop-release.test.mjs`. - The preparation function can be exercised using fixture artifacts and - does not call GitHub or publish anything. -3. Merge the tested PR; create a tag corresponding to the package version. - Four package jobs produce six archives. A dedicated script - (`scripts/prepare-desktop-release.mjs`) checks every artifact, renames - installers, generates update manifests and SHA256 checksums. The short - workflow publishes these assets with `.github/RELEASE_NOTES.md`. -4. Verify the published installers, macOS archives, update manifests, - checksums and release notes. Configure signing/notarization and - homologate upgrade, rollback and encrypted settings on real devices. - Unsigned macOS releases must not advertise automatic installation. +1. Merge PRs with Conventional Commits into `main`. The desktop workflow + calculates a version from the last stable `vX.Y.Z` tag. Documentation-only + and test-only changes do not cause a release. +2. For releasable commits, the same run stamps the calculated version into + npm metadata and compiles Linux, Windows and macOS packages. All four + builds and tests must pass before assets can be published. +3. The publish job validates canonical assets, update manifests and checksums, + generates notes from relevant commits, pushes the release tag and uploads + all packages to a **draft** GitHub release. It publishes the draft only + once the uploads have completed. +4. Do not manually bump the package version or create stable tags during + ordinary merges. The publishing job needs repository `contents: write`. + Tags pushed by the default `GITHUB_TOKEN` will not trigger another run; + build and publication intentionally happen in the same workflow. +5. If a tag was pushed but publication failed, manually run + `.github/workflows/desktop-release.yml` using its `release_tag` input + to rebuild that exact version. Never force-update a release tag or delete + a published release to hide failed publication. +6. Validate installation, automatic upgrades, rollback and preservation + of encrypted settings on physical Windows, macOS and Linux devices. + Successful automated builds are not a substitute for this verification. + +The tag source records the actual published package version; `main` does +not receive an automated version-only commit. Prerelease tags may still be +pushed manually when preparing a preview. diff --git a/scripts/desktop-version.mjs b/scripts/desktop-version.mjs index c669502..e1b89bc 100644 --- a/scripts/desktop-version.mjs +++ b/scripts/desktop-version.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node // SPDX-License-Identifier: GPL-3.0-or-later -// The Electron package is the single manually maintained desktop version. +// The Electron package is the single version source; release builds stamp it automatically. import { appendFileSync, readFileSync } from 'node:fs'; import { dirname, join, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; From f4ed9956367580283850fc099da6f0396ab13191 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:27:06 +0000 Subject: [PATCH 06/10] fix(ci): prevent untrusted pull requests from accessing release secrets Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .github/workflows/desktop-release.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml index 2f31129..deb2c57 100644 --- a/.github/workflows/desktop-release.yml +++ b/.github/workflows/desktop-release.yml @@ -87,13 +87,13 @@ jobs: NATIVEPHP_APP_VERSION: ${{ needs.plan.outputs.version }} CSC_IDENTITY_AUTO_DISCOVERY: 'false' # No signing credentials are available to untrusted pull requests. - CSC_LINK: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_CSC_LINK || '' }} - CSC_KEY_PASSWORD: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_CSC_KEY_PASSWORD || '' }} - NATIVEPHP_APPLE_ID: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_APPLE_ID || '' }} - NATIVEPHP_APPLE_ID_PASS: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_APPLE_ID_PASS || '' }} - NATIVEPHP_APPLE_TEAM_ID: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'mac' && secrets.MAC_APPLE_TEAM_ID || '' }} - WIN_CSC_LINK: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'win' && secrets.WIN_CSC_LINK || '' }} - WIN_CSC_KEY_PASSWORD: ${{ needs.plan.outputs.publish == 'true' && matrix.target == 'win' && secrets.WIN_CSC_KEY_PASSWORD || '' }} + CSC_LINK: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_CSC_LINK || '' }} + CSC_KEY_PASSWORD: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_CSC_KEY_PASSWORD || '' }} + NATIVEPHP_APPLE_ID: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_APPLE_ID || '' }} + NATIVEPHP_APPLE_ID_PASS: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_APPLE_ID_PASS || '' }} + NATIVEPHP_APPLE_TEAM_ID: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_APPLE_TEAM_ID || '' }} + WIN_CSC_LINK: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'win' && secrets.WIN_CSC_LINK || '' }} + WIN_CSC_KEY_PASSWORD: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'win' && secrets.WIN_CSC_KEY_PASSWORD || '' }} steps: - uses: actions/checkout@v4 @@ -209,7 +209,7 @@ jobs: retention-days: 7 publish: - if: needs.plan.outputs.publish == 'true' + if: needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request' needs: [plan, packages] runs-on: ubuntu-24.04 permissions: From 171e0d4635a4d75fd7276493d0151839aba83bdb Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:27:57 +0000 Subject: [PATCH 07/10] test(ci): validate squash PR titles for reliable release classification Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .github/workflows/conventional-commits.yml | 9 ++++++++- scripts/plan-desktop-release.mjs | 10 ++++++++++ scripts/plan-desktop-release.test.mjs | 9 ++++++++- 3 files changed, 26 insertions(+), 2 deletions(-) diff --git a/.github/workflows/conventional-commits.yml b/.github/workflows/conventional-commits.yml index 2e1aafa..6d74d6d 100644 --- a/.github/workflows/conventional-commits.yml +++ b/.github/workflows/conventional-commits.yml @@ -3,7 +3,7 @@ name: Conventional commits on: pull_request: - types: [opened, ready_for_review, reopened, synchronize] + types: [opened, edited, ready_for_review, reopened, synchronize] permissions: contents: read @@ -15,6 +15,13 @@ jobs: - uses: actions/checkout@v4 with: persist-credentials: false + - uses: actions/setup-node@v4 + with: + node-version: '22' + - name: Validate squash merge title + env: + PR_TITLE: ${{ github.event.pull_request.title }} + run: node scripts/plan-desktop-release.mjs --validate-title "$PR_TITLE" - uses: webiny/action-conventional-commits@7f91b1595ca1951cdb671ddc9f07a49081ec5b69 # v1.4.2 with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/scripts/plan-desktop-release.mjs b/scripts/plan-desktop-release.mjs index 853fe30..e941a1e 100644 --- a/scripts/plan-desktop-release.mjs +++ b/scripts/plan-desktop-release.mjs @@ -54,6 +54,9 @@ export function releaseDecision(previousTag, messages) { const version = nextVersion(previous.join('.'), level); return { publish: level !== 'none', version, tag: level === 'none' ? '' : 'v' + version, level, changes: relevant }; } +export function isConventionalTitle(title) { + return typeof title === 'string' && Boolean(conventionalChange(title).type); +} export function parseGitMessages(output) { return output.split('\0').map(message => message.trim()).filter(Boolean); } @@ -86,6 +89,13 @@ export function releaseNotes(template, messages, tag, previousTag) { } function run() { const [mode, ...args] = process.argv.slice(2); + if (mode === '--validate-title') { + if (!isConventionalTitle(args.join(' '))) { + throw new Error('Pull request title must follow Conventional Commits for squash merges'); + } + console.log('Conventional pull request title valid'); + return; + } if (mode === '--notes') { if (args.length !== 3) throw new Error('Usage: --notes '); const [baseSha, headSha, tag] = args; diff --git a/scripts/plan-desktop-release.test.mjs b/scripts/plan-desktop-release.test.mjs index 46f0f4c..fbf7422 100644 --- a/scripts/plan-desktop-release.test.mjs +++ b/scripts/plan-desktop-release.test.mjs @@ -5,8 +5,15 @@ import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, rmSy import { execFileSync } from 'node:child_process'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; -import { conventionalChange, latestStableTag, nextVersion, parseGitMessages, releaseDecision, releaseNotes } from './plan-desktop-release.mjs'; +import { conventionalChange, latestStableTag, nextVersion, parseGitMessages, releaseDecision, releaseNotes, isConventionalTitle } from './plan-desktop-release.mjs'; +test('PR titles are Conventional for squash merges, including non-releasing types', () => { + assert.equal(isConventionalTitle('feat(ci): auto release'), true); + assert.equal(isConventionalTitle('docs: adjust README'), true); + assert.equal(isConventionalTitle('fix!: incompatible fix'), true); + assert.equal(isConventionalTitle('Improve the release process'), false); + assert.equal(isConventionalTitle('Merge pull request #14'), false); +}); test('highest stable SemVer tag excludes prereleases and invalid tags', () => { assert.equal(latestStableTag(['v0.4.9', 'v0.10.0', 'v1.0.0-rc.1', 'v0.9.10', 'anything']), 'v0.10.0'); assert.equal(latestStableTag(['v0.4.0-beta.1', 'unrelated']), null); From 207620ccd45f7cbffa3ba907c22131ac375a60d3 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:30:40 +0000 Subject: [PATCH 08/10] test(ci): isolate and test release tag and publication orchestration Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- scripts/finalize-desktop-release.mjs | 84 +++++++++++++++++++++++ scripts/finalize-desktop-release.test.mjs | 76 ++++++++++++++++++++ 2 files changed, 160 insertions(+) create mode 100644 scripts/finalize-desktop-release.mjs create mode 100644 scripts/finalize-desktop-release.test.mjs diff --git a/scripts/finalize-desktop-release.mjs b/scripts/finalize-desktop-release.mjs new file mode 100644 index 0000000..35d03c9 --- /dev/null +++ b/scripts/finalize-desktop-release.mjs @@ -0,0 +1,84 @@ +#!/usr/bin/env node +// SPDX-License-Identifier: GPL-3.0-or-later +// Finalize already-validated release artifacts. The command runner is +// injectable so tags and GitHub publishing can be tested without network. +import { execFileSync } from 'node:child_process'; +import { existsSync, readdirSync, statSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { readDesktopVersion } from './desktop-version.mjs'; + +const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const TAG = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/; +function command(bin, args, quiet = false) { + return execFileSync(bin, args, { + cwd: ROOT, encoding: 'utf8', stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit', + }) || ''; +} +function outcome(run, bin, args) { + try { return { exists: true, value: String(run(bin, args, true)).trim() }; } + catch { return { exists: false, value: '' }; } +} + +export function finalizeDesktopRelease({ folder, tag, version, notesFile, baseSha = '', run = command }) { + if (!TAG.test(tag) || tag !== 'v' + version) throw new Error('Tag and package version disagree'); + if (!existsSync(notesFile) || !statSync(notesFile).isFile()) throw new Error('Release notes are missing'); + const names = readdirSync(folder).sort(); + if (!names.includes('SHA256SUMS.txt') || names.length < 7 || + names.some(name => !/^[A-Za-z0-9._-]+$/.test(name) || !statSync(join(folder, name)).isFile())) { + throw new Error('Release artifacts have not been validated'); + } + const files = names.map(name => join(folder, name)); + const existing = outcome(run, 'gh', ['release', 'view', tag, '--json', 'isDraft', '--jq', '.isDraft']); + if (existing.exists && existing.value !== 'true') throw new Error('Published release already exists'); + if (baseSha) { + if (!/^[0-9a-f]{40}$/.test(baseSha) || + String(run('git', ['rev-parse', 'HEAD'], true)).trim() !== baseSha) { + throw new Error('Release source HEAD changed'); + } + const changed = !outcome(run, 'git', [ + 'diff', '--quiet', '--', 'nativephp/electron/package.json', 'nativephp/electron/package-lock.json', + ]).exists; + if (changed) { + run('git', ['add', '--', 'nativephp/electron/package.json', 'nativephp/electron/package-lock.json']); + run('git', ['-c', 'user.name=github-actions[bot]', + '-c', 'user.email=41898282+github-actions[bot]@users.noreply.github.com', + 'commit', '-s', '-m', 'chore(release): ' + tag]); + } + if (outcome(run, 'git', ['show-ref', '--verify', '--quiet', 'refs/tags/' + tag]).exists) { + throw new Error('Release tag already exists; never overwrite tags'); + } + run('git', ['tag', tag]); + run('git', ['push', 'origin', 'refs/tags/' + tag]); + } else if (!outcome(run, 'git', ['rev-parse', '--verify', 'refs/tags/' + tag]).exists) { + throw new Error('Manual recovery requires an existing release tag'); + } + const isPreview = tag.includes('-'); + if (existing.exists) { + // A draft may be left behind by a failed upload; published releases + // must never be overwritten. Only repair a draft for the same tag. + run('gh', ['release', 'upload', tag, ...files, '--clobber']); + run('gh', ['release', 'edit', tag, '--notes-file', notesFile]); + } else { + run('gh', ['release', 'create', tag, ...files, '--verify-tag', '--draft', + '--title', 'Automatic Kimai ' + tag + (isPreview ? ' (prévia)' : ''), + ...(isPreview ? ['--prerelease'] : []), '--notes-file', notesFile]); + } + run('gh', ['release', 'edit', tag, '--draft=false', '--latest=' + String(!isPreview)]); + return { tag, files: files.length, repairedDraft: existing.exists }; +} + +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + try { + const [folder, tag, ...options] = process.argv.slice(2); + if (!folder || !tag || options.length > 2 || + (options.length > 0 && options[0] !== '--main-source')) { + throw new Error('Usage: finalize-desktop-release.mjs [--main-source ]'); + } + const baseSha = options[0] === '--main-source' ? options[1] : ''; + if (options.length && !baseSha) throw new Error('Main source SHA is required'); + const result = finalizeDesktopRelease({ folder: resolve(folder), tag, + version: readDesktopVersion(), notesFile: join(ROOT, 'release-notes.md'), baseSha }); + console.log('PUBLISHED_DESKTOP_RELEASE=' + result.tag); + } catch (error) { console.error(error.message); process.exitCode = 1; } +} diff --git a/scripts/finalize-desktop-release.test.mjs b/scripts/finalize-desktop-release.test.mjs new file mode 100644 index 0000000..e851ca3 --- /dev/null +++ b/scripts/finalize-desktop-release.test.mjs @@ -0,0 +1,76 @@ +// SPDX-License-Identifier: GPL-3.0-or-later +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { finalizeDesktopRelease } from './finalize-desktop-release.mjs'; + +const SHA = 'ab'.repeat(20); +function fixture(fn) { + const root = mkdtempSync(join(tmpdir(), 'automatic-kimai-finalize-')); + const folder = join(root, 'release-output'); + try { + mkdirSync(folder); + ['Automatic-Kimai-linux-x86_64.AppImage', 'Automatic-Kimai-windows-x64-setup.exe', + 'Automatic-Kimai-macos-arm64.dmg', 'Automatic-Kimai-macos-x64.dmg', + 'Automatic.Kimai-0.5.0-arm64.zip', 'Automatic.Kimai-0.5.0-x64.zip', + 'latest.yml', 'SHA256SUMS.txt'].forEach(file => writeFileSync(join(folder, file), 'test')); + const notesFile = join(root, 'notes.md'); + writeFileSync(notesFile, 'Release notes'); + fn({ folder, notesFile }); + } finally { rmSync(root, { recursive: true, force: true }); } +} +function fake({ draft = null, changed = true, uploadFailure = false } = {}) { + const calls = []; + const run = (bin, args) => { + calls.push([bin, ...args]); + if (bin === 'gh' && args[0] === 'release' && args[1] === 'view') { + if (draft === null) throw new Error('404 release missing'); + return draft ? 'true' : 'false'; + } + if (bin === 'gh' && args[0] === 'release' && args[1] === 'create' && uploadFailure) { + throw new Error('Upload failed'); + } + if (bin === 'git' && args[0] === 'rev-parse' && args[1] === 'HEAD') return SHA; + if (bin === 'git' && args[0] === 'rev-parse') return SHA; + if (bin === 'git' && args[0] === 'diff' && changed) throw new Error('Changes found'); + if (bin === 'git' && args[0] === 'show-ref') throw new Error('Tag missing'); + return ''; + }; + return { calls, run }; +} +const action = (calls, command, subcommand) => calls.filter(c => c[0] === command && c[1] === subcommand); + +test('stable release stamps tag commit and publishes only after uploads', () => fixture(({folder,notesFile}) => { + const { calls, run } = fake(); + const result = finalizeDesktopRelease({ folder, notesFile, tag:'v0.5.0', version:'0.5.0', baseSha:SHA, run }); + assert.equal(result.files, 8); + assert.equal(action(calls,'git','push').length, 1); + assert.equal(action(calls,'gh','release').filter(c => c[2] === 'create').length, 1); + assert.deepEqual(calls.at(-1).slice(-2), ['--draft=false', '--latest=true']); + assert.equal(calls.some(c => c.includes('commit') && c.includes('-s')), true); +})); +test('published release cannot be modified and no tag is pushed', () => fixture(({folder,notesFile}) => { + const { calls,run } = fake({draft:false}); + assert.throws(() => finalizeDesktopRelease({ folder, notesFile, tag:'v0.5.0', version:'0.5.0', baseSha:SHA, run }), /already exists/); + assert.equal(action(calls,'git','push').length, 0); +})); +test('a failed asset upload never publishes the release', () => fixture(({folder,notesFile}) => { + const { calls,run } = fake({uploadFailure:true}); + assert.throws(() => finalizeDesktopRelease({ folder, notesFile, tag:'v0.5.0', version:'0.5.0', baseSha:SHA, run }), /Upload failed/); + assert.equal(calls.some(c => c.includes('--draft=false')), false); +})); +test('draft recovery uploads and finalizes without altering its tag', () => fixture(({folder,notesFile}) => { + const { calls,run } = fake({draft:true}); + const result = finalizeDesktopRelease({ folder, notesFile, tag:'v0.5.0', version:'0.5.0', run }); + assert.equal(result.repairedDraft, true); + assert.equal(action(calls,'git','push').length, 0); + assert.equal(calls.some(c => c.includes('upload') && c.includes('--clobber')), true); + assert.deepEqual(calls.at(-1).slice(-2), ['--draft=false', '--latest=true']); +})); +test('bad tag fails before invoking external commands', () => fixture(({folder,notesFile}) => { + const { calls,run } = fake(); + assert.throws(() => finalizeDesktopRelease({ folder, notesFile, tag:'v0.5.1', version:'0.5.0', baseSha:SHA, run }), /disagree/); + assert.equal(calls.length, 0); +})); From 3e733f2bae970213350e9f14a37520c6d6020444 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:31:03 +0000 Subject: [PATCH 09/10] refactor(ci): make release publication a testable workflow step Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .github/workflows/desktop-release.yml | 42 ++++----------------------- .github/workflows/php-ci.yml | 2 +- 2 files changed, 6 insertions(+), 38 deletions(-) diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml index deb2c57..ae66e69 100644 --- a/.github/workflows/desktop-release.yml +++ b/.github/workflows/desktop-release.yml @@ -123,7 +123,7 @@ jobs: node scripts/desktop-version.mjs --github-env - name: Test versioning and release preparation without publishing shell: bash - run: node --test scripts/desktop-version.test.mjs scripts/create-update-manifests.test.mjs scripts/prepare-desktop-release.test.mjs scripts/plan-desktop-release.test.mjs + run: node --test scripts/desktop-version.test.mjs scripts/create-update-manifests.test.mjs scripts/prepare-desktop-release.test.mjs scripts/plan-desktop-release.test.mjs scripts/finalize-desktop-release.test.mjs - name: Install PHP dependencies shell: bash run: | @@ -254,28 +254,7 @@ jobs: if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then node scripts/plan-desktop-release.mjs --notes "$BASE_SHA" "$GITHUB_SHA" "$RELEASE_TAG" > release-notes.md fi - - name: Tag the versioned sources after successful builds - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - shell: bash - env: - RELEASE_TAG: ${{ needs.plan.outputs.tag }} - run: | - set -euo pipefail - git checkout --detach "$GITHUB_SHA" - if ! git diff --quiet -- nativephp/electron/package.json nativephp/electron/package-lock.json; then - git add -- nativephp/electron/package.json nativephp/electron/package-lock.json - git -c user.name='github-actions[bot]' \ - -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \ - commit -s -m "chore(release): ${RELEASE_TAG}" - fi - test "$(node scripts/desktop-version.mjs)" = "${RELEASE_TAG#v}" - if git show-ref --verify --quiet "refs/tags/${RELEASE_TAG}"; then - echo 'Release tag already exists; refusing to overwrite it' >&2 - exit 1 - fi - git tag "$RELEASE_TAG" - git push origin "refs/tags/${RELEASE_TAG}" - - name: Publish verified assets and finalize release + - name: Finalize versioned tag and publish verified assets env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} GH_REPO: ${{ github.repository }} @@ -283,19 +262,8 @@ jobs: shell: bash run: | set -euo pipefail - if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then - echo 'Release already exists; refusing duplicate publication' >&2 - exit 1 - fi - mapfile -d '' files < <(find release-output -maxdepth 1 -type f -print0) - if [[ "$RELEASE_TAG" == *-* ]]; then - gh release create "$RELEASE_TAG" "${files[@]}" --verify-tag --draft \ - --title "Automatic Kimai $RELEASE_TAG (prévia)" \ - --prerelease --notes-file release-notes.md - gh release edit "$RELEASE_TAG" --draft=false --latest=false + if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then + node scripts/finalize-desktop-release.mjs release-output "$RELEASE_TAG" --main-source "$GITHUB_SHA" else - gh release create "$RELEASE_TAG" "${files[@]}" --verify-tag --draft \ - --title "Automatic Kimai $RELEASE_TAG" \ - --notes-file release-notes.md - gh release edit "$RELEASE_TAG" --draft=false --latest + node scripts/finalize-desktop-release.mjs release-output "$RELEASE_TAG" fi diff --git a/.github/workflows/php-ci.yml b/.github/workflows/php-ci.yml index 7c3bd15..f5e6c7b 100644 --- a/.github/workflows/php-ci.yml +++ b/.github/workflows/php-ci.yml @@ -73,7 +73,7 @@ jobs: - name: Check build dependency security and compatibility run: node --test build/dependency-compat.test.mjs - name: Test desktop update flow and metadata - run: node --test src/main/updates.test.mjs ../../scripts/create-update-manifests.test.mjs ../../scripts/desktop-version.test.mjs ../../scripts/prepare-desktop-release.test.mjs ../../scripts/plan-desktop-release.test.mjs + run: node --test src/main/updates.test.mjs ../../scripts/create-update-manifests.test.mjs ../../scripts/desktop-version.test.mjs ../../scripts/prepare-desktop-release.test.mjs ../../scripts/plan-desktop-release.test.mjs ../../scripts/finalize-desktop-release.test.mjs - name: Validate canonical desktop version and lockfile run: node ../../scripts/desktop-version.mjs - name: Compile NativePHP Electron plugin (required for #plugin import) From ca1f73a9f0d2e95df59fdd18d0266fb9bb379e8a Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:31:31 +0000 Subject: [PATCH 10/10] fix(ci): require main branch for manual release recovery Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- scripts/plan-desktop-release.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scripts/plan-desktop-release.mjs b/scripts/plan-desktop-release.mjs index e941a1e..6630f1a 100644 --- a/scripts/plan-desktop-release.mjs +++ b/scripts/plan-desktop-release.mjs @@ -123,6 +123,9 @@ function run() { } } else if ((event === 'push' && refType === 'tag') || (event === 'workflow_dispatch' && requestedTag)) { + if (event === 'workflow_dispatch' && ref !== 'refs/heads/main') { + throw new Error('Manual release recovery must be dispatched from main'); + } const tag = event === 'workflow_dispatch' ? requestedTag : refName; if (!MANUAL_TAG.test(tag)) throw new Error('Invalid desktop release tag'); assertReleaseTag(current, 'tag', tag);