chore: initial sanitized public snapshot
This commit is contained in:
Aria2 Rust Pro Contributors
+134
@@ -0,0 +1,134 @@
|
||||
# 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](https://github.com/P3TERX/Aria2-Pro-Core)
|
||||
and the upstream [aria2 project](https://github.com/aria2/aria2). 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:
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user