# 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.