Contributing to aria2-rust-pro

Thanks for contributing to aria2-rust-pro.

This repository is maintained as a practical, compatibility-driven Rust 2024 implementation informed by Aria2-Pro-Core and the upstream aria2 project. The most helpful contributions 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:

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

branch from main
keep the edit scope tight and purpose-driven
follow existing crate boundaries instead of inventing new cross-cutting abstractions too early
add or update tests when behavior changes
run the relevant gates before asking for review

If your change affects release packaging or container behavior, also run the owned smoke path:

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. The usual closeout set is:

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:

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:

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:

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:

That keeps the repository ready for an actual external release instead of only an internal development snapshot.

4.6 KiB Raw Permalink Blame History