# Changelog
All notable changes to waddling-errors will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.5.0] - 2025-11-12
### Breaking Changes
- **Renamed `DocGenerator` to `DocRegistry`** - More accurate name reflecting its role as a registry rather than a generator. The actual generation is handled by renderer implementations.
- Update: `DocGenerator::new()` → `DocRegistry::new()`
- All method names remain the same
- **Changed `HtmlRenderer` from unit struct to struct with fields** - Enables HTML customization features.
- Update: `Box::new(HtmlRenderer)` → `Box::new(HtmlRenderer::new())`
- Or use: `HtmlRenderer::with_customization(customization)`
- **Removed deprecated `register_diagnostic()` method** - Use `register_diagnostic_complete()` instead for full metadata support.
### Added
- **HTML Customization System** - Complete branding and theming support for generated HTML documentation:
- `HtmlCustomization` builder with 8 customization methods
- Logo support (URL + alt text)
- Accent color customization (primary + hover colors)
- Custom CSS injection
- Custom JavaScript injection
- CSS variable override support
- Custom header/footer HTML
- Full CSS replacement capability
- **Asset Extraction** - Moved 2,436 lines of CSS/JS to external files:
- `src/doc_generator/html/assets/default.css` (1,073 lines)
- `src/doc_generator/html/assets/default.js` (1,363 lines)
- Assets loaded via `include_str!()` at compile time
- **New Examples**:
- `html_customization_demo.rs` - Demonstrates all HTML customization features
- Updated `complete_system` example with full DocRegistry API usage
### Changed
- Improved code organization with cleaner separation of concerns
- Enhanced documentation with new guides:
- `HTML_CUSTOMIZATION.md` - Complete guide to HTML theming
- `DOC_GENERATION_GUIDE.md` - Updated for DocRegistry
- `ARCHITECTURE_ANALYSIS.md` - Documents v0.5.0 changes
### Fixed
- Fixed unused variable warning when `hash` feature is disabled
- Fixed all clippy warnings (4 auto-fixed, 3 manually allowed)
- Updated all doc tests to use new API
### Development
- Added cargo-hack testing for feature matrix validation (145 feature combinations verified)
- All tests passing (17 unit + 23 doc tests)
- Zero clippy warnings
- Consistent formatting with cargo fmt
## [0.4.0] - Previous Release (Trait-Based Extensibility & Enhanced Metadata)
- **Trait-based component and primary types** - `ComponentId` and `PrimaryId` traits
- Define your own component/primary enums for full type safety
- No need to request additions to waddling-errors
- Pattern matching and IDE autocomplete support
- Three levels of implementation:
- Level 1: Minimal (`ComponentId`, `PrimaryId`) - just `.as_str()`
- Level 2: Documented (`ComponentIdDocumented`, `PrimaryIdDocumented`) - add metadata
- Level 3: Full (`ErrorMetadata`) - complete error documentation
- **`Code<C, P>` is now generic** over component and primary types
- Full type safety with your own enums
- Pattern matching support in match expressions
- IDE autocomplete for components and primaries
- **Enhanced DiagnosticMetadata** - 5 new fields for richer documentation:
- `tags: &'static [&'static str]` - Classification labels (e.g., ["security", "api", "breaking-change"])
- `related_codes: &'static [&'static str]` - Cross-references to related error codes
- `docs_url: Option<&'static str>` - Link to detailed documentation
- `introduced: Option<&'static str>` - Version when diagnostic was introduced
- `deprecated: Option<&'static str>` - Version when diagnostic was deprecated
- **`Role` enum** - for documentation visibility (Public/Internal/Developer)
- **Examples streamlined** - Only 3 essential examples:
- `trait_based_enums.rs` - Core: demonstrates custom enum types
- `trait_based_documented.rs` - Advanced: shows documentation traits
- `wasm_minimal.rs` - no_std: proves zero-cost abstraction
### Changed
- `Code` struct is now generic: `Code<C: ComponentId, P: PrimaryId>`
- Component and primary are no longer restricted to `&'static str`
- Users define their own types implementing the traits
- **BREAKING**: String-based API removed - use trait-based enums only
- Cleaned up 24 legacy examples, keeping only 3 essential ones
### Migration Guide
**v0.3.0 → v0.4.0** - Define your own enums:
```rust
use waddling_errors::{Code, ComponentId, PrimaryId};
#[derive(Debug, Clone, Copy)]
enum Component { Parser, Crypto }
impl ComponentId for Component {
fn as_str(&self) -> &'static str {
match self {
Component::Parser => "PARSER",
Component::Crypto => "CRYPTO",
}
}
}
#[derive(Debug, Clone, Copy)]
enum Primary { Syntax, Salt }
impl PrimaryId for Primary {
fn as_str(&self) -> &'static str {
match self {
Primary::Syntax => "SYNTAX",
Primary::Salt => "SALT",
}
}
}
// Now fully type-safe with pattern matching!
const ERR: Code<Component, Primary> = error(Component::Crypto, Primary::Salt, 1);
// Example with new metadata fields (using waddling-errors-macros):
diag! {
E.Crypto.Salt.MISSING: {
message: "Salt '{salt}' not found",
fields: [salt],
description: "Cryptographic operation requires a salt value",
hints: ["Check your configuration", "Generate a new salt"],
tags: ["security", "crypto", "production"],
related_codes: ["E.Crypto.Key.MISSING", "E.Crypto.Salt.WEAK"],
docs_url: "https://docs.example.com/crypto/salt",
introduced: "v1.0.0",
}
}
```
### Breaking Changes
- ❌ String-based API removed - must use trait-based enums
- ❌ No backward compatibility with v0.3.0 string literals
- ✅ Migration is straightforward - see examples above
## [0.3.0] - 2025-10-26
### Added
- **Help severity** - New severity level between Warning and Success
- `Severity::Help` (H) for helpful suggestions and recommendations
- `Code::help()` constructor
- Top-level `help()` function
- 💡 emoji (light bulb) with `emoji` feature
- Green ANSI color with `ansi-colors` feature
- Priority level: 4 (between Success and Warning)
### Changed
- **Priority scale expanded** from 0-7 to 0-8 to accommodate Help severity
- Priority assignments updated:
- Error: 7 → 8
- Blocked: 6 → 7
- Critical: 5 → 6
- Warning: 4 → 5
- Help: (new) 4
- Success: 3 (unchanged)
- Completed: 2 (unchanged)
- Info: 1 (unchanged)
- Trace: 0 (unchanged)
### Migration Guide
If you have exhaustive `match` statements on `Severity`, add a new arm:
```rust
match severity {
Severity::Error => { /* ... */ }
// ... other variants ...
Severity::Help => { /* handle helpful suggestions */ }
// ... remaining variants ...
}
```
Or use a catch-all pattern to remain future-proof:
```rust
match severity {
Severity::Error | Severity::Blocked => { /* blocking */ }
_ => { /* non-blocking */ }
}
```
## [0.2.0] - 2025-10-25
### Added
- **Semantic methods** for `Severity`:
- `is_blocking()` - Check if severity blocks execution (Error, Blocked)
- `is_positive()` - Check if severity indicates success (Success, Completed)
- `is_negative()` - Check if severity indicates problems (Error, Warning, Critical, Blocked)
- `is_neutral()` - Check if severity is informational (Info, Trace)
- `priority()` - Get numeric priority (0-7)
- `description()` - Get human-readable description
- **Emoji support** (behind `emoji` feature flag):
- `emoji()` method returns unicode emoji for each severity
- ❌ Error, 🚫 Blocked, 🔥 Critical, ⚠️ Warning, ✅ Success, ✔️ Completed, ℹ️ Info, 🔍 Trace
- **ANSI color support** (behind `ansi-colors` feature flag):
- `ansi_color()` method returns ANSI escape codes
- Color coding for terminal output
- **Serde support** (behind `serde` feature flag):
- Serialize/Deserialize for `Severity` and `Code`
- **Ord implementation** for `Severity` based on priority
- Comprehensive examples demonstrating all features
- Feature flags documentation (`FEATURE_FLAGS.md`)
- Release documentation (`RELEASE.md`)
- Publishing guide (`docs/maintenance/PUBLISHING.md`)
### Changed
- **BREAKING**: `emoji()` method now requires `emoji` feature flag (was always available)
- **BREAKING**: Removed deprecated `level()` method in favor of `priority()`
- Modularized codebase from single 846-line file to 4 focused modules:
- `lib.rs` (107 lines) - Re-exports and prelude
- `severity.rs` (264 lines) - Severity enum with methods
- `code.rs` (221 lines) - Code struct implementation
- `hash.rs` (58 lines) - Optional hashing module
- Updated README with feature flag documentation
- Reduced README size by 42% (698 → 404 lines) by removing redundancy
- Changed Critical emoji from ⚠️ to 🔥 to avoid collision with Warning
### Fixed
- Example feature requirements now properly declared in Cargo.toml
- Tests properly gated behind feature flags
## [0.1.0] - TBD
### Added
- Initial release
- Core error code standard: `SEVERITY.COMPONENT.PRIMARY.SEQUENCE`
- 8 severity levels: Error, Blocked, Critical, Warning, Success, Completed, Info, Trace
- `Code` struct with formatting and validation
- Optional base62 hashing (behind `hash` feature flag)
- Comprehensive documentation and examples
- Zero dependencies by default
[Unreleased]: https://gitlab.com/AshutoshMahala/waddling-errors/compare/v0.2.0...HEAD
[0.2.0]: https://gitlab.com/AshutoshMahala/waddling-errors/compare/v0.1.0...v0.2.0
[0.1.0]: https://gitlab.com/AshutoshMahala/waddling-errors/releases/tag/v0.1.0