134 lines
4.5 KiB
Markdown
134 lines
4.5 KiB
Markdown
# 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.
|