# Gitea releases for this fork

The release destination is
https://git.sorokin-oleg-edu.xyz/replicated/learnharness.
Version **0.6.1 is Linux x64 AppImage-only**; follow the dedicated procedure below.
The historical **0.6.0 release targets Linux x64 and Windows x64**, with each platform built
and verified on its native operating system. The upstream GitHub workflow and three-platform packaging
configuration remain available as reference in `.github/workflows/release.yml`
and `electron-builder.yml`.

Official fork packages use `electron-builder.gitea.yml`, which inherits the
upstream packaging and replaces its update origin with:

```
https://git.sorokin-oleg-edu.xyz/replicated/learnharness/releases/download/latest
```

Gitea's `latest` alias resolves the most recent published, non-prerelease release.
Drafts do not become updates. The repository and published downloads must be
public; no API credential is embedded in the application.

## 0.6.1: Linux x64 AppImage-only upload and verification

This release has exactly three attachments:

- `LearnHarness-0.6.1-x86_64.AppImage`
- `latest-linux.yml`
- `SHA256SUMS`

No Windows, macOS, Debian (`.deb`), or RPM packages belong in this release.
Use `docs/release-0.6.1.md` for the release notes. The procedures below this
section retain the historical 0.6.0/full-release instructions; do not use their
Debian/Windows asset inventory for 0.6.1.

Stage only the three listed files for upload. Before upload, generate and verify
checksums using the existing helper's explicit offline AppImage-only mode:

```sh
node scripts/gitea-release.mjs checksums dist --appimage-only
node scripts/gitea-release.mjs verify dist --appimage-only
```

Run these commands from the 0.6.1 source checkout. They validate the AppImage,
feed version, filename, size, SHA-512, and SHA-256 manifest. `SHA256SUMS` must
cover only the AppImage and `latest-linux.yml`. The offline verifier checks the
expected files, not the absence of unrelated files: separately check that the
upload selection contains exactly the three names above. Confirm the packaged
`resources/app-update.yml` has the generic provider and the current update URL
shown above before uploading.

The unchanged `desktop:release:linux` script still builds AppImage and Debian
packages, so do not use it or the historical manual Actions workflow for this
AppImage-only release. Package explicitly with:

```sh
electron-builder --config electron-builder.gitea.yml --linux AppImage --x64 --publish never
```

After building and verifying the copied server/runtime, verify the embedded
updater with `node scripts/gitea-release.mjs verify-package dist/linux-unpacked`.
The helper uses the current host and accepts `--appimage-only` for `checksums`,
`verify`, `upload`, and `verify-remote`; omitting this flag retains the historical
AppImage-plus-Debian inventory. Supply `GITEA_TOKEN` privately for API operations:

```sh
node scripts/gitea-release.mjs upload dist --appimage-only
node scripts/gitea-release.mjs verify-remote dist --appimage-only
```

The uploader creates or reuses a draft and verifies downloaded attachment bytes;
it does not publish the release. Publication is a separate explicitly authorized
API action after these checks pass.

After the release tag `v0.6.1` exists at the intended source commit in the current
Gitea repository, create or review a draft for that tag on
`git.sorokin-oleg-edu.xyz`. Set its notes from `docs/release-0.6.1.md` and explicitly
upload only the three listed files. Before publication:

1. Confirm the draft tag is `v0.6.1` and its attachment inventory is exactly the
   three names above, with sizes matching the locally verified files.
2. Download those three draft attachments into a separate directory and run
   `node scripts/gitea-release.mjs verify /path/to/downloaded-assets --appimage-only`
   from the 0.6.1 source checkout. Compare the downloaded `SHA256SUMS` byte-for-byte
   with the locally verified manifest; stop on any mismatch.
3. Review the notes and asset exclusions. Publication is a separate,
   explicitly authorized action; a draft does not update installed clients.

After authorized publication, confirm the current host's public
`releases/download/latest/latest-linux.yml` resolves to version `0.6.1` and
references `LearnHarness-0.6.1-x86_64.AppImage` with the verified size and SHA-512.

## Historical 0.6.0 / full-release instructions

The following commands and asset inventories are retained for reference. Their
upload tooling still defaults to the old host; they are not the current 0.6.1
upload procedure.

## Preparing Linux packages

Use Node **26**, matching upstream's release gates. Build from a clean checkout
of the intended release commit. Keep `.env*`, local keys, and application data out
of the build directory. Next can copy loaded environment files after tracing;
`build-server.mjs` refuses a payload containing them. A clean worktree avoids
loading these files in the first place.

```sh
npm ci
npm run typecheck
npm test
npm run lint
ELECTRON_RUN_AS_NODE=1 npx electron --import tsx --test tests/pdf-native-render.test.ts tests/pdf-ops.test.ts tests/svg-native-render.test.ts tests/browser-service.test.ts
npm run desktop:release:linux
```

The release script builds the standalone server, initializes providers offline,
curates the payload, boots it under Electron's bundled Node, packages AppImage
and Debian installers, checks the packaged Gitea updater configuration, creates SHA-256 checksums, and verifies update metadata
against the actual installer bytes.

Run the packaged-runtime gates too:

```sh
node scripts/smoke-provider-runtime.mjs --standalone dist/linux-unpacked/resources/server/standalone
node scripts/smoke-provider-runtime.mjs --standalone dist/linux-unpacked/resources/server/standalone --runtime dist/linux-unpacked/learnharness
xvfb-run -a node scripts/smoke-demo-runtime.mjs --standalone dist/linux-unpacked/resources/server/standalone --runtime dist/linux-unpacked/learnharness --browser
```

The Linux portion of 0.6.0 has these attachments:

- `LearnHarness-0.6.0-x86_64.AppImage`
- `LearnHarness-0.6.0-amd64.deb`
- `latest-linux.yml`
- `SHA256SUMS`

## Preparing Windows packages

Use a clean checkout of the same `v0.6.0` tag on Windows x64 with Node 26 and Git
for Windows. Keep build tools and logs outside the checkout. The Windows
release checkout is `~/Documents/Gitea/learnharness-release-0.6.0`, linked to the
existing repository in `~/Documents/Gitea/learnharness`.

In PowerShell, stop after any failed command:

```powershell
npm.cmd ci
$env:NODE_ENV = 'test'
$env:ELECTRON_RUN_AS_NODE = '1'
node node_modules/electron/cli.js --import tsx --test tests/pdf-native-render.test.ts tests/pdf-ops.test.ts tests/svg-native-render.test.ts tests/browser-service.test.ts
Remove-Item Env:ELECTRON_RUN_AS_NODE
node --import tsx --test tests/i18n.test.tsx
Remove-Item Env:NODE_ENV
node node_modules/next/dist/bin/next build
node scripts/smoke-provider-runtime.mjs
node scripts/build-server.mjs
node scripts/smoke-server.mjs --electron
node node_modules/electron-builder/out/cli/cli.js --config electron-builder.gitea.yml --win --x64 --publish never
node scripts/gitea-release.mjs verify-package dist/win-unpacked
node scripts/smoke-provider-runtime.mjs --standalone dist/win-unpacked/resources/server/standalone
node scripts/smoke-provider-runtime.mjs --standalone dist/win-unpacked/resources/server/standalone --runtime dist/win-unpacked/LearnHarness.exe
node scripts/smoke-demo-runtime.mjs --standalone dist/win-unpacked/resources/server/standalone --runtime dist/win-unpacked/LearnHarness.exe --browser
```

Windows contributes three attachments:

- `LearnHarness-0.6.0-x64-setup.exe`
- `LearnHarness-0.6.0-x64-setup.exe.blockmap`
- `latest.yml`

The combined release has **seven attachments**, including one `SHA256SUMS`
covering all six other files. Verify that `latest.yml` names the Windows
installer exactly, reports version `0.6.0`, and matches the installer's actual
size and SHA-512. Its gzip blockmap must cover the installer and match every
block checksum. Confirm the packaged `resources/app-update.yml` uses the Gitea
generic provider. Windows builds follow upstream's unsigned, per-user installer
configuration.

## Preparing a Linux-only Gitea draft

Commit and push the release source, then push its exact annotated tag:

```sh
git tag -a v0.6.0 -m 'LearnHarness 0.6.0'
git push gitea main v0.6.0
```

Supply `GITEA_TOKEN` only to the upload command. A token file may remain outside
the clean build checkout:

```sh
node --env-file=/path/to/private/release.env scripts/gitea-release.mjs upload dist
```

The tool requires the tag to exist in Gitea, creates or reuses one draft at that
tag, uploads missing assets, and downloads every attachment to verify its actual
SHA-256 against the local verified build. Existing mismatched attachments and
published releases are refused. It never publishes or changes repository
visibility. Release notes come from `docs/release-0.6.0.md`.

This uploader and its remote verifier enforce a **Linux-only** inventory. They
will refuse a combined Linux/Windows draft. For the combined 0.6.0 release, add
the verified Windows attachments to the existing draft and replace `SHA256SUMS`
with the combined manifest. Keep the Linux installers and feed unchanged. Check
all seven attachment names and sizes against the verified local builds. For
the owner-approved 0.6.0 release, local installer/feed/blockmap validation and
the combined checksum manifest are completed before upload. Confirm successful
upload responses and publish immediately afterward; do not download attachments
again or run post-upload hash checks. Do not publish until both platforms'
local checks pass.

A separate verification can be repeated without changing the draft:

```sh
node --env-file=/path/to/private/release.env scripts/gitea-release.mjs verify-remote dist
```

Review the verified draft before publication. Only after publication will the
public `latest` feed and in-app automatic updates expose this version.

## Gitea Actions

`.gitea/workflows/release.yml` provides the same Linux gates through a manual
workflow with an existing release tag as input. It requires a native Linux x64
runner labeled `ubuntu-24.04`, the label used by upstream's Linux release job,
plus the native Electron dependencies and `xvfb-run`. There were no runners
registered when 0.6.0 was prepared, so its packages are built locally. A tag push
does not queue a job that cannot run.

The workflow uses the repository's ephemeral `GITEA_TOKEN` with release-write
permission only in the final upload step. It checks out the requested tag without
persisting credentials and leaves the result as a verified draft. Public pull
requests cannot trigger this publishing workflow. This workflow remains
Linux-only; the combined 0.6.0 draft was assembled from local native builds.
Windows has its own standalone payload and smoke checks, as described above.