managing-cargo-dependencies

# Cargo Dependencies Management Guidance for adding and managing dependencies in Cargo.toml files within the HASH repository's workspace structure. ## Core Principles **HASH uses a strict workspace dependency pattern:** ✅ **DO:** - Add external dependencies to workspace root `[workspace.dependencies]` - Use caret version specifiers (e.g., `version = "1.0.0"` = `^1.0.0`) - Set `default-features = false` for all dependencies unless specifically needed - Use `workspace = true` in package Cargo.toml - Organize dependencies into 4 sections with comment headers - Use `public = true` for dependencies exposed in public API - Align dependency names using spaces for readability ❌ **DON'T:** - Add version numbers directly in package Cargo.toml - Use exact versions with `=` prefix (e.g., `=1.0.0`) in workspace root - Enable `default-features` without considering impact - Mix different dependency types without section comments - Forget `public = true` for dependencies exposed in public API ## Quick Reference ### The 4-Section Pattern Every package `Cargo.toml` must organize dependencies into these sections: ```toml [dependencies] # Public workspace dependencies hash-graph-types = { workspace = true, public = true } hashql-core = { workspace = true, public = true } # Public third-party dependencies serde = { workspace = true, public = true, features = ["derive"] } tokio = { workspace = true, public = true } # Private workspace dependencies error-stack = { workspace = true } hash-codec = { workspace = true } # Private third-party dependencies tracing = { workspace = true } regex = { workspace = true } ``` **Keep all 4 section comments even if a section is empty.** ### Quick Add Process 1. **Check workspace root** - Is dependency already there? 2. **Add to workspace if needed** - With caret version `1.2.3` 3. **Determine section** - Public workspace/third-party or private? 4. **Add to package** - Use `workspace = true` (+ `public = true` if needed) ## Detailed Guides Choose the guide that matches the task: ### [workspace-setup.md](references/workspace-setup.md) **Use when:** Adding new dependencies to workspace root - How to add external crates to workspace - Version pinning with exact versions - Default features configuration - Workspace member paths ### [package-dependencies.md](references/package-dependencies.md) **Use when:** Adding dependencies to a package Cargo.toml - The 4-section organizational structure - Public vs private dependencies - When to use `public = true` - Alignment and formatting rules - Feature configuration ### [examples-reference.md](references/examples-reference.md) **Use when:** Looking for real examples from HASH codebase - Complete examples from `@local/codec` - Complete examples from `@local/hashql/core` - Optional dependencies pattern - dev-dependencies structure ## Common Patterns ### Adding a New External Dependency ```toml # 1. Add to workspace root Cargo.toml [workspace.dependencies] my-crate = { version = "1.2.3", default-features = false } # 2. Add to package Cargo.toml (appropriate section) [dependencies] # Private third-party dependencies my-crate = { workspace = true } ``` ### Making a Dependency Public ```toml # Use when the dependency appears in your public API serde = { workspace = true, public = true, features = ["derive"] } tokio = { workspace = true, public = true } ``` ### Optional Dependencies ```toml [dependencies] serde = { workspace = true, optional = true, features = ["derive"] } [features] serde = ["dep:serde", "other-dep/serde"] ``` ## References - [workspace-setup.md](references/workspace-setup.md) - Workspace root configuration - [package-dependencies.md](references/package-dependencies.md) - Package dependency structure - [examples-reference.md](references/examples-reference.md) - Real codebase examples - [Workspace Cargo.toml](../../../Cargo.toml) - Root workspace configuration - [hash-codec/Cargo.toml](../../../libs/@local/codec/Cargo.toml) - Reference example - [hashql-core/Cargo.toml](../../../libs/@local/hashql/core/Cargo.toml) - Reference example