# 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.
