Changelog & Version History
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The "Changelog & Version History" system in KamehaDB serves as the authoritative record of project evolution, documenting new features, bug fixes, and breaking changes. It follows the Keep a Changelog standard to provide a clear, human-readable timeline for developers and users. The system is integrated into both the repository root for development tracking and the project's landing site for public consumption.
KamehaDB manages versioning through a centralized CHANGELOG.md file located at the repository root. This file is parsed programmatically to drive the visual timeline on the documentation site, ensuring that the marketing presence and technical reality remain synchronized. Versioning logic is critical for the project's CI/CD release workflow, which triggers builds based on semantic version tags.
Sources: CHANGELOG.md:1-4, landing/src/app/changelog/page.tsx:112-123, AGENTS.md:144-150
Changelog Architecture & Data Flow
The changelog system operates by parsing a Markdown source file into structured TypeScript objects. This allows the same data to be used for GitHub releases, the landing page UI, and automated version tracking.
Data Model
The system uses specific interfaces to represent the hierarchy of a release:
- Release: Represents a version (e.g.,
v1.1.0), its release date, a high-level description, and categorized change sections. - ChangeSection: Groups changes by type, such as "Added", "Fixed", or "Changed".
- ChangeGroup: Provides sub-categorization within sections (e.g., "AI & Vector Search" under "Added").
Sources: landing/src/app/changelog/page.tsx:21-40
Processing Flow
The landing site utilizes a dedicated parser within the Next.js environment to transform the raw Markdown text from the root CHANGELOG.md into the Release[] structure.
The parser identifies version headers using the regex /^## \[(.+?)\](?:\s*—\s*(.+))?$/ and section types via /^### (.+)$/.
Sources: landing/src/app/changelog/page.tsx:42-108, landing/src/app/changelog/page.tsx:138-151
Versioning Standards and Categories
KamehaDB categorizes all changes into standardized sections to maintain clarity across the version history.
| Section Type | Purpose | UI Color Coding |
|---|---|---|
| Added | For new features or capabilities added to the database GUI or sidecar. | Emerald (Green) |
| Changed | For changes in existing functionality that are not bug fixes. | Blue |
| Fixed | For any bug fixes or stability improvements. | Amber (Yellow) |
| Removed | For now-deprecated features that have been removed from the codebase. | Red |
Sources: CHANGELOG.md:8-12, landing/src/app/changelog/page.tsx:154-159
Release Workflow & CI Integration
Versions are formally released through a structured GitHub Actions workflow. The process is strictly tied to the version history documented in the changelog.
Release Execution
- Tagging: Releases are triggered by pushing tags matching the
v*pattern (e.g.,v0.1.0-rc.1). - Drafting: The workflow creates a draft GitHub release.
- Building: The system builds platform-specific bundles for macOS (
.dmg), Windows (.exe,.msi), and Linux (.deb,.AppImage,.rpm). - Verification: All user-facing changes must be recorded in
CHANGELOG.mdunder an[Unreleased]header prior to the merge that triggers the release.
Sources: AGENTS.md:144-150, AGENTS.md:255-265
Major Version History Highlights
The project has evolved through several key milestones, transitioning from a basic SQL browser to an AI-integrated multi-engine database tool.
v1.1.0: AI & Vector Search Integration
- Vector Support: Added Qdrant integration and semantic schema retrieval.
- AI Streaming: Implemented server-sent events (SSE) for real-time AI chat responses.
- Smart Querying: Added term expansion (e.g., "germany" to "DE") and fuzzy matching for schema terms.
v1.0.0: First Stable Release
- Multi-Engine Parity: Achieved full support for PostgreSQL, MySQL, SQLite, MongoDB, and Redis.
- Visualization: Introduced ER diagram generation using ReactFlow and dagre layout.
- Local-First Architecture: Stabilized the sidecar + desktop app structure for private credential management.
Sources: CHANGELOG.md:14-48, CHANGELOG.md:126-150, PLAN.md:195-210
Conclusion
The Changelog & Version History of KamehaDB is a critical architectural component that bridges the gap between technical development and user documentation. By maintaining a single source of truth in the root CHANGELOG.md and programmatically rendering it on the landing site, the project ensures transparency in its evolution from a local SQL utility to a feature-rich, AI-enhanced database management ecosystem. This system facilitates a predictable release cycle and maintains high standards for documenting the project's transition toward stable, cross-platform performance.