Crockan/aria2-rust-pro
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

chore: initial sanitized public snapshot

Browse Source
This commit is contained in:
Aria2 Rust Pro Contributors
2026-07-18 16:01:12 +08:00
commit 7c6b6a3746
321 changed files with 76896 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/release/README.md
+305
View File
@@ -0,0 +1,305 @@
# 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>\`.
docs/release/RELEASE-NOTES-TEMPLATE.md
+69
View File
@@ -0,0 +1,69 @@
# aria2-rust-pro Release Notes Template
Use this template when cutting a public-facing release, local handoff package,
or Gitea release page.
---
## Summary
One short paragraph that answers:
- what this release is
- who should care
- whether this is mainly a feature release, compatibility release, packaging
release, or bugfix release
## Highlights
- highlight 1
- highlight 2
- highlight 3
## Compatibility Notes
- [aria2](https://github.com/aria2/aria2) baseline:
- [Aria2-Pro-Core](https://github.com/P3TERX/Aria2-Pro-Core) behavior notes:
- Docker compatibility notes:
- RPC compatibility notes:
## Packaging
Artifacts included in this release:
- Windows:
- Linux:
- Docker image tar or image tag:
Checksums:
- `SHA256SUMS.txt` included: yes or no
- manifest files included: yes or no
## Migration Notes
Operator actions required before upgrade:
- config changes:
- compose or Docker env changes:
- host deployment changes:
- rollback considerations:
## Verification
Commands or evidence used to validate the release:
```text
list the exact commands run
```
## Known Limits
- limit 1
- limit 2
## Full Change List
- item
- item
- item
docs/release/v1.0.0.md
+77
View File
@@ -0,0 +1,77 @@
# aria2-rust-pro 1.0.0
`aria2-rust-pro 1.0.0` is the first public release of this independently
maintained Rust implementation.
This release establishes a versioned baseline for the project:
- a public Git tag for the Rust 2024 workspace
- Cargo-native local packaging and Docker export workflows
- repository-local migration, deployment, and compatibility documentation
## Project Sources
- [Aria2-Pro-Core](https://github.com/P3TERX/Aria2-Pro-Core) is the direct
compatibility and migration reference for the enhanced deployment profile.
- [aria2](https://github.com/aria2/aria2) is the upstream project whose public
CLI, configuration, and RPC contracts guide this implementation.
## Highlights
- independently maintained Rust 2024 implementation informed by those sources
- Cargo-native release packaging and Docker export automation
- compatibility-led CLI, configuration, JSON-RPC, and XML-RPC development
## Compatibility Notes
- version smoke preserves the upstream-compatible first line
`aria2 version 1.37.0`
- Docker images keep the `aria2c` entrypoint shape by symlinking
`aria2c -> aria2-rust-pro`
- migration and deployment guides remain in-repo under `docs/migration/` and
`docs/deployment/`
## Artifacts
The release includes these built artifacts:
- `aria2-rust-pro-v1.0.0-x86_64-pc-windows-msvc.zip`: Windows x86_64 archive
with the executable, debug symbols, release documentation, a manifest, and
an individual SHA-256 checksum.
- `aria2-rust-pro-v1.0.0-x86_64-unknown-linux-gnu.tar.gz`: Linux x86_64
archive with the executable, release documentation, a manifest, and an
individual SHA-256 checksum.
- `aria2-rust-pro-v1.0.0-aarch64-unknown-linux-gnu.tar.gz`: Linux arm64
archive with the executable, release documentation, a manifest, and an
individual SHA-256 checksum.
- `aria2-rust-pro-docker-v1.0.0.tar`: Linux amd64 Docker image archive tagged
`aria2-rust-pro:v1.0.0`, with a manifest and individual SHA-256 checksum.
- `RELEASE-SHA256SUMS.txt`: aggregate SHA-256 checksums for the four primary
archives.
Load the Docker archive with:
```sh
docker load -i aria2-rust-pro-docker-v1.0.0.tar
```
Verify an archive before use with its adjacent `.sha256` file or the aggregate
checksum list.
## Verification
The repository release workflow is intended to perform:
- workspace fast gates
- nightly `cargo udeps`
- `cargo deny`
- release version smoke
- daemon-free Docker smoke
- daemon-backed Docker smoke
- local release packaging
- Docker image export
## Known Limits
- macOS and Windows arm64 archives are not included in this release
- broader multi-platform release archives remain future work