chore: initial sanitized public snapshot

2026-07-18 14:04:26 +08:00
commit 7b3816441c
320 changed files with 76813 additions and 0 deletions
@@ -0,0 +1,133 @@
+# Contributing to aria2-rust-pro
+
+Thanks for contributing to `aria2-rust-pro`.
+
+This repository is maintained as a practical, compatibility-driven rewrite of
+Aria2-Pro-Core on top of a Rust 2024 workspace. The most helpful contributions
+are the ones that improve behavior, compatibility evidence, packaging, and
+maintainability without drifting the external aria2-facing contract.
+
+## Development Setup
+
+Recommended local prerequisites:
+
+- Rust toolchain from `rust-toolchain.toml`
+- PowerShell 7 on Windows
+- Docker Desktop or a compatible Docker daemon for image validation
+- `rtk` for compact command output and the repository's preferred terminal flow
+
+From the repository root:
+
+```powershell
+rtk cargo metadata --manifest-path .\Cargo.toml --no-deps --format-version 1
+rtk cargo check --workspace --all-targets --all-features --locked
+rtk cargo nextest run --workspace --all-targets --all-features --locked
+```
+
+## Preferred Workflow
+
+1. branch from `main`
+2. keep the edit scope tight and purpose-driven
+3. follow existing crate boundaries instead of inventing new cross-cutting
+   abstractions too early
+4. add or update tests when behavior changes
+5. run the relevant gates before asking for review
+
+If your change affects release packaging or container behavior, also run the
+owned smoke path:
+
+```powershell
+rtk cargo run --manifest-path .\xtask\Cargo.toml -- release smoke-version
+rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker smoke-local
+```
+
+## Required Quality Gates
+
+The expected final gates are documented in
+[docs/testing/quality-gates.md](docs/testing/quality-gates.md). The usual
+closeout set is:
+
+```powershell
+rtk cargo fmt --all --check
+rtk cargo check --workspace --all-targets --all-features --locked
+rtk cargo nextest run --workspace --all-targets --all-features --locked
+rtk cargo clippy --workspace --all-targets --all-features --locked --no-deps -- -D warnings -D clippy::pedantic -D clippy::nursery -D clippy::cargo
+rtk cargo +nightly udeps --workspace --all-targets --all-features --locked
+rtk cargo deny --locked check
+```
+
+For a one-shot local sweep:
+
+```powershell
+pwsh ./scripts/testing/strict-sweep.ps1
+```
+
+## Repository Conventions
+
+- Prefer Cargo-native `xtask` entrypoints over ad hoc scripts when both exist.
+- Keep public-facing behavior compatible unless the change is an intentional,
+  documented divergence.
+- Preserve release evidence: manifests, checksums, version-smoke validation,
+  and migration notes matter here.
+- Prefer `rtk` commands for repo work.
+- Keep documentation in sync when changing deployment, Docker, migration, or
+  packaging behavior.
+
+### Commit Messages
+
+Use Conventional Commits for every authored commit:
+
+```text
+type(scope)!: concise summary
+```
+
+Allowed types are `feat`, `fix`, `perf`, `refactor`, `test`, `docs`, `build`,
+`ci`, `chore`, and `revert`. The scope and `!` are optional. Use `!` or a
+`BREAKING CHANGE:` footer for intentional compatibility breaks. CI validates
+non-merge commits after the `v1.0.0` baseline.
+
+### Versioning and Changelog
+
+The workspace package version in the root `Cargo.toml` is the release version.
+Internal crate constraints are centralized in `[workspace.dependencies]`; do
+not add crate-local copies. Release tags remain `vMAJOR.MINOR.PATCH` and must
+match the workspace version.
+
+- `feat` is a minor-release candidate.
+- `fix` and `perf` are patch-release candidates.
+- `!` or `BREAKING CHANGE:` requires a major-release decision.
+- `docs`, `refactor`, `test`, `build`, `ci`, and `chore` do not independently
+  require a version bump.
+
+`git-cliff` generates user-facing entries from Conventional Commits. Run the
+following preview before a release-facing change:
+
+```powershell
+rtk git-cliff --config .\cliff.toml --unreleased
+```
+
+### Dependency Updates
+
+Renovate creates dependency pull requests against `main`. Patch updates may
+automerge only after CI succeeds; minor and major updates always remain review
+pull requests. Lockfile maintenance is also review-only.
+
+## Pull Requests and Reviews
+
+When opening a review:
+
+- summarize the behavior change in plain language
+- list the exact verification commands you ran
+- call out compatibility-sensitive areas explicitly
+- mention any remaining limits or follow-up work instead of hiding them
+
+## Release-Facing Changes
+
+If your change affects users directly, also update at least one of:
+
+- [CHANGELOG.md](CHANGELOG.md)
+- [docs/release/RELEASE-NOTES-TEMPLATE.md](docs/release/RELEASE-NOTES-TEMPLATE.md)
+- [docs/migration/README.md](docs/migration/README.md)
+
+That keeps the repository ready for an actual external release instead of only
+an internal development snapshot.