# Changelog Format Ideas
## Option 1: Keep a Changelog Standard
https://keepachangelog.com/
**Format:**
```markdown
# Changelog
All notable changes to this project 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).
## [Unreleased]
### Added
- Feature X for use case Y
### Changed
- Improved performance of Z
### Fixed
- Bug in parser for format A
## [0.9.1] - 2024-11-10
### Added
- Full documentation site at kelora.dev
- Comprehensive performance benchmarks vs jq, grep, awk, qsv, mlr, angle-grinder
- 40+ built-in Rhai functions
- Parallel processing mode with `--parallel`
- Sliding window support with `--window`
- Multi-format support (JSON, logfmt, syslog, CSV, TSV, cols, combined)
### Security
- Integration with cargo-audit for dependency scanning
- cargo-deny for license and advisory enforcement
- Comprehensive test coverage (532 tests)
## [0.8.0] - 2024-XX-XX
...
```
**Pros:**
- Industry standard
- Clear categorization
- Easy to scan
- Good for users
**Cons:**
- Can get verbose
- Need to maintain manually
- Commit discipline required
---
## Option 2: GitHub Releases Only
Skip CHANGELOG.md entirely, use GitHub Releases as the canonical changelog.
**Format:**
- Tag each release: `v0.9.1`
- Write release notes in GitHub UI
- Auto-generate from commits or hand-curate
- Link from README to releases page
**Pros:**
- Single source of truth
- GitHub renders nicely
- Can attach binaries
- Less duplication
**Cons:**
- Not in repository
- Requires web access to read
- Less discoverable
---
## Option 3: Minimal Highlights
Brief, high-level changelog that doesn't try to capture everything.
**Format:**
```markdown
# Changelog
## 0.9.1 (2024-11-10)
First public release with comprehensive documentation and benchmarks.
- 40+ built-in functions for log analysis
- Multiple format parsers (JSON, logfmt, syslog, CSV, cols)
- Parallel processing mode
- Full documentation site at kelora.dev
- Benchmarks vs 7 competing tools
## 0.8.0 (2024-10-15)
Internal testing release. Added windowing and metrics.
## 0.7.0 (2024-09-20)
Early prototype with basic parsing and Rhai integration.
```
**Pros:**
- Low maintenance
- Focuses on what users care about
- Easy to skim
- Less commitment to detail
**Cons:**
- Missing granular changes
- Not useful for tracking API changes
- Pre-1.0 users might want more detail
---
## Option 4: Hybrid (Recommended)
Minimal CHANGELOG.md + detailed GitHub Releases
**CHANGELOG.md:**
```markdown
# Changelog
See [GitHub Releases](https://github.com/dloss/kelora/releases) for detailed release notes.
## Recent Releases
- **0.9.1** (2024-11-10) - Public release with docs and benchmarks
- **0.8.0** (2024-10-15) - Windowing and metrics
- **0.7.0** (2024-09-20) - Early prototype
```
**GitHub Releases:** Full details, categorized changes, breaking changes, etc.
**Pros:**
- Best of both worlds
- CHANGELOG.md provides quick overview
- GitHub Releases for deep dive
- Reduces duplication
**Cons:**
- Need to maintain both (but minimal effort for CHANGELOG.md)
---
## Recommendation
For a solo, pre-1.0 project: **Option 3 (Minimal Highlights)** or **Option 4 (Hybrid)**
**Why:**
- Pre-1.0 means API will change
- Solo maintainer means time is precious
- Not enough users yet to need granular tracking
- Can always expand later if needed
**When to switch to Option 1:**
- Post-1.0 when stability matters
- Multiple active users depending on API stability
- Regular, predictable release cadence
---
## Draft CHANGELOG.md (Option 3 style)
```markdown
# Changelog
## [0.9.1] - 2024-11-11
First public release.
**Highlights:**
- 40+ built-in Rhai functions for log analysis (parse_jwt, mask_ip, track_percentile, etc.)
- Multiple format parsers: JSON, logfmt, syslog, CSV/TSV, custom column specs, Apache combined
- Parallel processing mode for multi-core throughput
- Sliding window support for context-aware analysis
- Comprehensive documentation site at https://kelora.dev
- Honest performance benchmarks vs grep, jq, awk, qsv, miller, angle-grinder, klp
- 532 passing tests, cargo-audit and cargo-deny integration
- Available via cargo install, GitHub releases for macOS/Linux/Windows
**What it does:**
Parse structured and semi-structured logs, filter/transform with embedded Rhai scripts,
emit clean output. Built for complex multi-stage pipelines where grep/jq/awk would
require multiple tools and bash glue.
**Not production-ready:**
This is a 0.x release generated by AI agents. API will change. Inspect code before
production use. See SECURITY.md and Development Approach in README.
---
## Pre-release Development
**0.8.x** - Internal testing with windowing, metrics, and span aggregation
**0.7.x** - Early prototype exploring Rhai integration and format parsers
**0.6.x and earlier** - Experimentation phase
```
---
## Alternative: Just Use GitHub Releases
If you want zero maintenance, skip CHANGELOG.md and just write good release notes in GitHub.
Add this to README:
```markdown
## Release Notes
See [GitHub Releases](https://github.com/dloss/kelora/releases) for version history and changelogs.
```
Then each release gets a tag + description. GitHub can auto-generate from commits or you hand-write them.