|
| 1 | +# Contributing to parallel-disk-usage |
| 2 | + |
| 3 | +## Commit Message Convention |
| 4 | + |
| 5 | +This project uses [Conventional Commits](https://www.conventionalcommits.org/). |
| 6 | + |
| 7 | +### Format |
| 8 | + |
| 9 | +``` |
| 10 | +type(scope): lowercase description |
| 11 | +``` |
| 12 | + |
| 13 | +### Rules |
| 14 | + |
| 15 | +- **Types:** `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `chore`, `ci`, `test`, `lint` |
| 16 | +- **Scopes** (optional): `cli`, `api`, `deps`, `readme`, `benchmark`, `toolchain`, `test`, or other relevant area |
| 17 | +- **Description:** always lowercase after the colon, no trailing period, brief (3-7 words preferred) |
| 18 | +- **Breaking changes:** append `!` before the colon (e.g. `feat(cli)!: remove deprecated flag`) |
| 19 | +- **Code identifiers** in descriptions should be wrapped in backticks (e.g. `` chore(deps): update `rand` ``) |
| 20 | + |
| 21 | +### Exception: Version Releases |
| 22 | + |
| 23 | +Version release commits use **only** the version number as the message — no type prefix: |
| 24 | + |
| 25 | +``` |
| 26 | +0.21.1 |
| 27 | +``` |
| 28 | + |
| 29 | +## Code Style |
| 30 | + |
| 31 | +Automated tools enforce formatting (`cargo fmt`) and linting (`cargo clippy`). The following conventions are **not** enforced by those tools and must be followed manually. |
| 32 | + |
| 33 | +### Import Organization |
| 34 | + |
| 35 | +Prefer **merged imports** — combine multiple items from the same crate or module into a single `use` statement with braces rather than separate `use` lines. Import ordering is enforced by `cargo fmt`. Platform-specific imports (`#[cfg(unix)]`) go in a separate block after the main imports. |
| 36 | + |
| 37 | +```rust |
| 38 | +use crate::{ |
| 39 | + args::{Args, Quantity, Threads}, |
| 40 | + bytes_format::BytesFormat, |
| 41 | + size, |
| 42 | +}; |
| 43 | +use clap::Parser; |
| 44 | +use pipe_trait::Pipe; |
| 45 | +use std::{io::stdin, time::Duration}; |
| 46 | + |
| 47 | +#[cfg(unix)] |
| 48 | +use crate::get_size::{GetBlockCount, GetBlockSize}; |
| 49 | +``` |
| 50 | + |
| 51 | +### Module Organization |
| 52 | + |
| 53 | +- Use the flat file pattern (`module.rs`) rather than `module/mod.rs` for submodules. |
| 54 | +- List `pub mod` declarations first, then `pub use` re-exports, then private imports and items. |
| 55 | +- Use `pub use` to re-export key types at the module level for convenience. |
| 56 | + |
| 57 | +```rust |
| 58 | +pub mod error_only_reporter; |
| 59 | +pub mod error_report; |
| 60 | +pub mod event; |
| 61 | + |
| 62 | +pub use error_only_reporter::ErrorOnlyReporter; |
| 63 | +pub use error_report::ErrorReport; |
| 64 | +pub use event::Event; |
| 65 | +``` |
| 66 | + |
| 67 | +- Type aliases using `pub use ... as ...` are used to provide semantic alternative names: |
| 68 | + |
| 69 | +```rust |
| 70 | +pub use Reflection as DataTreeReflection; |
| 71 | +``` |
| 72 | + |
| 73 | +### Derive Macro Ordering |
| 74 | + |
| 75 | +When deriving multiple traits, use this order and split across multiple `#[derive(...)]` lines for readability: |
| 76 | + |
| 77 | +1. **Standard traits:** `Debug`, `Default`, `Clone`, `Copy` |
| 78 | +2. **Comparison traits:** `PartialEq`, `Eq`, `PartialOrd`, `Ord` |
| 79 | +3. **Hash** |
| 80 | +4. **`derive_more` traits:** `Display`, `From`, `Into`, `Add`, `AddAssign`, etc. |
| 81 | +5. **Feature-gated derives** on a separate `#[cfg_attr(...)]` line |
| 82 | + |
| 83 | +```rust |
| 84 | +#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] |
| 85 | +#[derive(From, Into, Add, AddAssign, Sub, SubAssign, Sum)] |
| 86 | +#[cfg_attr(feature = "json", derive(Deserialize, Serialize))] |
| 87 | +pub struct Bytes(u64); |
| 88 | +``` |
| 89 | + |
| 90 | +### Generic Parameter Naming |
| 91 | + |
| 92 | +Use **descriptive names** for type parameters, not single letters: |
| 93 | + |
| 94 | +- `Size`, `Name`, `SizeGetter`, `HardlinksRecorder`, `Report` |
| 95 | + |
| 96 | +Single-letter generics are acceptable only in very short, self-contained trait impls. |
| 97 | + |
| 98 | +### Trait Bounds |
| 99 | + |
| 100 | +Prefer `where` clauses over inline bounds when there are multiple constraints: |
| 101 | + |
| 102 | +```rust |
| 103 | +impl<Size, SizeGetter, HardlinksRecorder, Report> |
| 104 | + From<FsTreeBuilder<'a, Size, SizeGetter, HardlinksRecorder, Report>> |
| 105 | + for DataTree<OsStringDisplay, Size> |
| 106 | +where |
| 107 | + Report: Reporter<Size> + Sync + ?Sized, |
| 108 | + Size: size::Size + Send + Sync, |
| 109 | + SizeGetter: GetSize<Size = Size> + Sync, |
| 110 | + HardlinksRecorder: RecordHardlinks<Size, Report> + Sync + ?Sized, |
| 111 | +``` |
| 112 | + |
| 113 | +### Visibility |
| 114 | + |
| 115 | +- Use `pub` for the public API surface. |
| 116 | +- Use `pub(crate)` for items shared within the crate but not exposed externally. |
| 117 | +- Default to private for everything else. |
| 118 | + |
| 119 | +### Error Handling |
| 120 | + |
| 121 | +- Define custom error enums with `#[derive(Debug, Display, Error)]` from `derive_more`. |
| 122 | +- Mark error enums as `#[non_exhaustive]`. |
| 123 | +- Minimize `unwrap()` in non-test code — use proper error propagation. `unwrap()` is acceptable in tests and for provably infallible operations (with a comment explaining why). When deliberately ignoring an error, use `.ok()` with a comment explaining why. |
| 124 | + |
| 125 | +```rust |
| 126 | +#[derive(Debug, Display, Error)] |
| 127 | +#[non_exhaustive] |
| 128 | +pub enum RuntimeError { |
| 129 | + #[display("SerializationFailure: {_0}")] |
| 130 | + SerializationFailure(serde_json::Error), |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +### Documentation Comments |
| 135 | + |
| 136 | +- Use `///` doc comments for all public types, traits, functions, and fields. |
| 137 | +- Use `//!` module-level doc comments at the top of `lib.rs` and significant modules. |
| 138 | +- Include usage examples with `/// ```no_run` blocks for key public APIs. |
| 139 | +- Reference related types with `[`backtick links`](crate::path)` syntax. |
| 140 | + |
| 141 | +### Feature Gating |
| 142 | + |
| 143 | +- Use `#[cfg(feature = "...")]` for optional functionality (e.g., `json`, `cli`). |
| 144 | +- Use `#[cfg(unix)]` for POSIX-specific code. |
| 145 | +- Use `#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]` for conditional derives. |
| 146 | + |
| 147 | +### Pattern Matching |
| 148 | + |
| 149 | +Use exhaustive matching. When mapping enum variants to values, prefer the concise wrapping style: |
| 150 | + |
| 151 | +```rust |
| 152 | +ExitCode::from(match self { |
| 153 | + RuntimeError::SerializationFailure(_) => 2, |
| 154 | + RuntimeError::DeserializationFailure(_) => 3, |
| 155 | +}) |
| 156 | +``` |
| 157 | + |
| 158 | +### Struct Field Ordering |
| 159 | + |
| 160 | +Order fields logically by purpose, not alphabetically. Group related fields together. Document every public field with `///` comments. |
| 161 | + |
| 162 | +### Macros |
| 163 | + |
| 164 | +Use macros to reduce boilerplate for repetitive patterns (e.g. newtype wrappers, trait impls for multiple numeric types). Keep macros well-scoped and documented. |
| 165 | + |
| 166 | +### Warnings Policy |
| 167 | + |
| 168 | +The crate uses `#![deny(warnings)]` — all warnings are treated as errors. Code must compile warning-free. |
| 169 | + |
| 170 | +## Setup |
| 171 | + |
| 172 | +Install the required Rust toolchain and components before running any checks: |
| 173 | + |
| 174 | +```sh |
| 175 | +rustup toolchain install "$(< rust-toolchain)" |
| 176 | +rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy |
| 177 | +``` |
| 178 | + |
| 179 | +## Automated Checks |
| 180 | + |
| 181 | +Before submitting, ensure: |
| 182 | + |
| 183 | +- `cargo fmt -- --check` passes |
| 184 | +- `cargo clippy` passes (on all feature combinations) |
| 185 | +- `cargo test` passes |
| 186 | +- The project builds with no default features, default features, and all features |
| 187 | + |
| 188 | +The CI script `test.sh` runs all of these across 5 feature combinations. You can run it locally with: |
| 189 | + |
| 190 | +```sh |
| 191 | +FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh |
| 192 | +``` |
0 commit comments