diff --git a/LOCAL_DEVELOPMENT.md b/LOCAL_DEVELOPMENT.md new file mode 100644 index 000000000..cec85f7ca --- /dev/null +++ b/LOCAL_DEVELOPMENT.md @@ -0,0 +1,62 @@ +# Tracing – Local development notes + +This document complements `CONTRIBUTING.md` with a short, task-oriented checklist for local development. + +## 1. Prerequisites + +- A recent stable Rust toolchain installed via `rustup` +- `cargo fmt` and `cargo clippy` components installed +- Recommended: `rustup component add rustfmt clippy` + +You can verify your toolchain with: + +~~~bash +rustc --version +cargo --version +~~~ + +## 2. Run the full test suite + +To run tests for the entire workspace: + +~~~bash +cargo test --all +~~~ + +To run tests for a specific crate, for example `tracing-subscriber`: + +~~~bash +cargo test -p tracing-subscriber +~~~ + +## 3. Formatting and linting + +Before opening a pull request, format the code and run Clippy: + +~~~bash +cargo fmt --all +cargo clippy --all-targets --all-features -- -D warnings +~~~ + +This helps keep the code style consistent and prevents new warnings from being introduced. + +## 4. Building documentation + +To build and inspect the documentation locally: + +~~~bash +cargo doc --all-features +# or open docs in a browser +cargo doc --all-features --open +~~~ + +## 5. Suggested workflow before a PR + +1. `cargo fmt --all` +2. `cargo clippy --all-targets --all-features -- -D warnings` +3. `cargo test --all` +4. Commit and push your changes +5. Open a pull request and briefly describe: + - What you changed + - Why the change is useful + - How you tested it locally