aria2-rust-pro/docs/release/README.md

Release Packaging and Local Deployment

This document covers the current local release workflow for aria2-rust-pro. The scripts under scripts/release/ cover three concrete needs:

• host-runnable --version smoke validation;
• deterministic local artifact naming plus SHA-256 generation;
• packaging of the current workspace's Windows or Linux release binary into a ready-to-share archive.
• exporting a locally built Docker image tag into a portable tar archive under dist\docker\.

As of the Phase 3 Cargo-native workflow push, the primary entrypoints now live in xtask/. The PowerShell files under scripts/release/ remain as thin compatibility shims so existing local habits still work, but the canonical project automation surface is now:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release smoke-version
rtk cargo run --manifest-path .\xtask\Cargo.toml -- release package-local
rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker smoke-local
rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker smoke

These commands do not update progress.md or the compatibility ledger, and they do not claim cross-host release certification by themselves. They are local release helpers for the current workspace state.

Files

• xtask/: canonical Cargo-native workflow entrypoints for release smoke and local packaging.
• scripts/release/smoke-version.ps1: thin shim around xtask release smoke-version.
• scripts/release/package-local.ps1: thin shim around xtask release package-local.
• scripts/docker/smoke-local.ps1: thin shim around xtask docker smoke-local.
• scripts/docker/smoke.ps1: thin shim around xtask docker smoke.
• scripts/docker/export-local.ps1: thin shim around xtask docker export-local.
• docs/release/RELEASE-NOTES-TEMPLATE.md: reusable release-page and handoff template for public-facing releases.

Artifact naming

The package script emits archives named like:

• aria2-rust-pro-v1.0.0-x86_64-pc-windows-msvc.zip
• aria2-rust-pro-v1.0.0-x86_64-unknown-linux-gnu.tar.gz

The target triple always stays in the file name so mixed-host staging stays unambiguous.

Output defaults to the workspace-level dist area:

dist\release\v<version>\

Generated files per package run:

• the archive itself (.zip on Windows targets, .tar.gz otherwise);
• <archive>.sha256;
• SHA256SUMS.txt;
• <artifact>.manifest.json.

Version smoke

From the repo root:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release smoke-version
pwsh ./scripts/release/smoke-version.ps1

Build first, then smoke:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release smoke-version --build
pwsh ./scripts/release/smoke-version.ps1 -Build

Smoke a specific binary:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release smoke-version --binary-path .\target\release\aria2-rust-pro.exe
pwsh ./scripts/release/smoke-version.ps1 -BinaryPath .\target\release\aria2-rust-pro.exe

The command succeeds only when the rendered banner keeps the upstream-compatible first line aria2 version 1.37.0 and also contains Rust rewrite package: aria2-rust-pro <workspace-version>.

Versioning and changelog

The workspace version in the root Cargo.toml is the source of truth. Release tags must use vMAJOR.MINOR.PATCH and match that version. Preview the next user-facing changelog entry with:

rtk git-cliff --config .\cliff.toml --unreleased

For a release tag, a checked-in docs/release/vX.Y.Z.md remains authoritative. When it is absent, the release workflow generates the Gitea release body from cliff.toml and the Conventional Commit history.

On an actual release tag, the release workflow compares each public workspace crate against the preceding SemVer tag with cargo-semver-checks. The first release tag has no predecessor and therefore skips that comparison.

Packaging the current host build

Build and package the host release binary:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release package-local --build
pwsh ./scripts/release/package-local.ps1 -Build

Package an already-built host binary without rebuilding:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release package-local
pwsh ./scripts/release/package-local.ps1

Write artifacts to a custom directory:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release package-local --build --output-root .\dist\release
pwsh ./scripts/release/package-local.ps1 -Build -OutputRoot .\dist\release

Packaging Windows and Linux artifacts from the current workspace

Windows host, Windows artifact

On the current Windows workspace, the default path uses:

• target\release\aria2-rust-pro.exe
• optional target\release\aria2_rust_pro.pdb

The archive is a .zip containing the binary, optional PDB, root README.md, and the release packaging guide under docs/release/README.md. Version-specific release notes such as docs/release/v1.0.0.md are used as Gitea release body text, not bundled into every archive by default.

Linux host, Linux artifact

On Linux with PowerShell 7 and Cargo available, the same script works:

pwsh ./scripts/release/package-local.ps1 -Build

The Linux archive format is .tar.gz, and the default packaged binary path is target/release/aria2-rust-pro.

Cross-target handling from one workspace

When the binary already exists under a target-specific Cargo directory, pass the target triple:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release package-local --build --target-triple x86_64-pc-windows-msvc
rtk cargo run --manifest-path .\xtask\Cargo.toml -- release package-local --build --target-triple x86_64-unknown-linux-gnu
pwsh ./scripts/release/package-local.ps1 -Build -TargetTriple x86_64-pc-windows-msvc
pwsh ./scripts/release/package-local.ps1 -Build -TargetTriple x86_64-unknown-linux-gnu

If the workspace cannot execute the packaged binary on the current host, package the prebuilt file directly and skip the runtime smoke:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- release package-local --target-triple x86_64-unknown-linux-gnu --source-binary .\target\x86_64-unknown-linux-gnu\release\aria2-rust-pro --skip-version-smoke
pwsh ./scripts/release/package-local.ps1 `
  -TargetTriple x86_64-unknown-linux-gnu `
  -SourceBinary .\target\x86_64-unknown-linux-gnu\release\aria2-rust-pro `
  -SkipVersionSmoke

That flow supports current-workspace staging for non-host artifacts, but the runtime smoke must still be re-run on a compatible machine before calling the artifact release-ready.

Local deployment checklist

1. Unpack the archive to a clean directory.
2. Run the binary with --version and confirm the expected workspace version.
3. Compare the archive checksum with either <archive>.sha256 or SHA256SUMS.txt.
4. For container deployment, keep using the documented docker/ workflow plus xtask docker smoke, xtask docker smoke-local, or xtask docker export-local. The matching scripts/docker/*.ps1 files are compatibility wrappers for those Cargo-native commands.
5. For direct CLI deployment, provide the same config/session/runtime paths you already use for local compatibility testing.

Exporting a local Docker image tar

When the Docker daemon is available and a local image exists or can be built:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker export-local --build
pwsh ./scripts/docker/export-local.ps1 -Build

That command writes a tar archive, checksum files, and a manifest under:

dist\docker\v<version>\

The default tag is aria2-rust-pro:local. To export another tag:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker export-local --tag aria2-rust-pro:smoke
pwsh ./scripts/docker/export-local.ps1 -Tag aria2-rust-pro:smoke

Docker smoke checks

After packaging or deployment changes, run the Cargo-native Docker smokes from the repo root:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker smoke-local
rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker smoke --tag aria2-rust-pro:smoke

xtask docker smoke-local proves the entrypoint/config-generation path without a Docker daemon. xtask docker smoke builds the image, starts a container, checks generated config, and probes live JSON-RPC inside the running container.

The PowerShell scripts are compatibility wrappers around the same commands:

pwsh ./scripts/docker/smoke-local.ps1
pwsh ./scripts/docker/smoke.ps1 -Tag aria2-rust-pro:smoke

The daemon-backed wrapper also forwards -Build, -HostRpcPort, -RpcSecret, and -SpecialMode to the matching xtask docker smoke options.

Self-hosted Gitea release verification

The self-hosted Gitea release workflow should be validated before cleaning up old runner records in the Gitea UI. Keep runner cleanup as an infrastructure follow-up, not part of the first release recovery step.

Use this order after CI has gone green on main:

1. Trigger the release workflow with workflow_dispatch and leave validation_only=true, or run the equivalent release commands on the runner host. Validation mode runs the release gates from the current ref and skips Gitea publishing, so it can test the runner without mutating an existing release.
2. Confirm the strict gate reaches the daemon-backed Docker smoke and that xtask docker smoke completes its JSON-RPC probe.
3. Confirm xtask docker export-local --build --tag aria2-rust-pro:release stages the Docker tar, manifest, and SHA256SUMS.txt.
4. For an actual tag-publish run, set validation_only=false or push a release tag, then confirm scripts/ci/publish-gitea-release.sh can create or update the Gitea release with all staged assets.
5. Only after the release workflow has passed, remove stale offline runner UI records that no longer correspond to the active runner.

Do not delete the active runner registration while release validation is still in progress. The current production runner identity should be confirmed from the latest passing Gitea Actions run before any old offline entry is removed. Do not move an already published tag just to validate the workflow; use the default no-publish validation mode instead.

Recovered runner evidence:

• release validation run 107 passed on commit 6d4956b with validation_only=true;
• push CI run 108 passed on the same commit;
• the release validation spent roughly 720 seconds in fast gates and 784 seconds in strict gates, while checkout, tool bootstrap, release package, and Docker export were short;
• no stale GITEA-ACTIONS containers or persisted temporary Gitea tokens should remain after runner-side validation.

Treat those timings as a baseline when optimizing the self-hosted runner. Prefer persistent Cargo registry/git cache or further runner-image prebaking before target-directory caching, because target caches can be polluted by toolchain, feature, and commit differences.

Scope and remaining release limits

These scripts are the active local release helpers:

• they stage host artifacts and Docker image tar exports from the current workspace;
• they do not, by themselves, certify that the current tree has reclosed every reopened modernization phase;
• archived release records are preserved only as historical evidence under docs/archive/;
• Docker image publication/signing still remains an external release-management concern, while export-local.ps1 and xtask docker export-local stage a portable tar from the local daemon state under dist\docker\v<version>\.