Release process

av-tools is licensed GPL-3.0-or-later. A publishable release is the exact reviewed source tag, production ZIP/checksum, Corresponding Source and third-party notices distributed together. The steps below fail closed where practical.

1. Resolve legal/source identity

The repository already declares the application licence and immutable third-party source identities. Before any distribution:

commit the reviewed GPL-3.0-or-later source;
create and verify annotated tag v0.1.0 at that exact commit;
push the commit and tag to the canonical public repository;
assemble, review and publish corresponding source and exact external notices for both core packages and linked libraries;
keep the manifest/package metadata, SOURCE.md, ZIP and tag version aligned.

SOURCE.md pins FFmpeg, ffmpeg.wasm, x264 and LAME by full commit. Do not describe the complete bundle as MIT-only.

2. Reproducible checks

With Node 22+ and the lockfile:

npm ci
npm run fixtures:verify
npm run check
npm run test:browser

check verifies manifest/vendor assets, types, lint/format, unit tests, production build and toolbox-check dist. Browser tests must exercise ST, MT, ST fallback, cancellation/recovery, nested paths and no runtime CDN request. Record exact results in the release report.

3. Package

Normal packaging validates the root GPL version 3 text and matching GPL-3.0-or-later package/manifest metadata:

npm run package:release
npm run source:package

The legacy development-only escape hatch is retained only for checking an otherwise unlicensed temporary fixture:

npm run package:release -- --allow-unlicensed-development-smoke

Pass --force only to replace the exact same-version ZIP and sidecar. Output:

release/av-tools-0.1.0.zip
release/av-tools-0.1.0.zip.sha256
release/ffmpeg-core-0.12.10-corresponding-source.tar.xz
release/ffmpeg-core-0.12.10-corresponding-source.tar.xz.sha256

Verify independently:

node scripts/checksum-release.mjs
(cd release && sha256sum -c ffmpeg-core-0.12.10-corresponding-source.tar.xz.sha256)
unzip -l release/av-tools-0.1.0.zip
tar -tJf release/ffmpeg-core-0.12.10-corresponding-source.tar.xz

The packager:

rejects symlinks, special files, traversal, absolute/ambiguous/duplicate archive paths and credential-like files;
rejects source maps and local absolute paths in text release files;
requires entry, manifest, icon and every declared asset;
requires root CHANGELOG.md, SOURCE.md, THIRD_PARTY_NOTICES.md, LICENSES/, assets/ and vendor/;
adds installed runtime npm licence files;
sorts paths, stores files as mode 0644, uses 1980-01-01 00:00:00 UTC and produces deterministic ZIP32 bytes;
excludes node_modules, test fixtures and source because it starts from dist plus an explicit legal/document list.

When used against a fixture without an application licence, the escape hatch adds DEVELOPMENT-ONLY-NOT-FOR-DISTRIBUTION.txt inside the ZIP.

4. Portal assembly smoke

Use the clean reference clone beside av-tools, never the user's active Portal worktree:

npm run portal:smoke -- \
  --artifact release/av-tools-0.1.0.zip \
  --allow-known-header-gap

The smoke harness clones the exact Portal HEAD to a temporary directory, copies the ZIP there, writes a temporary one-app lock derived from release/toolbox.lock.example.json, runs npm ci, tests, build and assembly, then verifies the generated catalogue/release records and copied FFmpeg assets. The temporary directory is removed unless --keep-temp is explicitly passed. No machine-specific path is committed and no Portal worktree is changed.

Without --allow-known-header-gap, the clean immutable Portal reference's CSP omission of media-src blob: is a failing deployment check. The override still reports the gap and is only for testing archive assembly. See docs/PORTAL_REQUIREMENTS.md.

The user's active /mnt/DATA/git/toolbox-portal worktree contains the narrow directive as a local patch, but the smoke intentionally does not consume that mutable worktree. Until the patch exists in a reviewed immutable Portal revision, retain the clean-reference failure/override behavior above.

5. Publish only reviewed bytes

From a clean v0.1.0 checkout, rerun all checks, create the ZIP once, verify the sidecar, assemble that exact ZIP through Portal, and publish the immutable ZIP, .zip.sha256, manifest, changelog, Corresponding Source and notices. Put its exact lowercase digest/version/id/target in a reviewed Portal lock. Never use mutable “latest” URLs or credentials in a lock.

The final report must state inspected commits, exact packages/build config, capabilities, completed tested milestones, all check results, artifact paths, Portal result, fixture provenance, licence status, headers, gaps, performance and browser limits. A UI or command builder alone is not a completed milestone.

4.9 KiB Raw Blame History