306 lines
12 KiB
Markdown
306 lines
12 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
rtk cargo run --manifest-path .\xtask\Cargo.toml -- release smoke-version
|
|
pwsh ./scripts/release/smoke-version.ps1
|
|
```
|
|
|
|
Build first, then smoke:
|
|
|
|
```powershell
|
|
rtk cargo run --manifest-path .\xtask\Cargo.toml -- release smoke-version --build
|
|
pwsh ./scripts/release/smoke-version.ps1 -Build
|
|
```
|
|
|
|
Smoke a specific binary:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
rtk cargo run --manifest-path .\xtask\Cargo.toml -- release package-local
|
|
pwsh ./scripts/release/package-local.ps1
|
|
```
|
|
|
|
Write artifacts to a custom directory:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
dist\docker\v<version>\
|
|
```
|
|
|
|
The default tag is `aria2-rust-pro:local`. To export another tag:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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>\`.
|