Skip to content

Add documentation changelog page #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
javier wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add documentation changelog page #359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
123f871
Add documentation changelog page
javier Feb 4, 2026
8df7fdd
Merge branch 'main' into jv/changelog
javier Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 177 additions & 0 deletions claude_changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
## Changelog Generation

When asked to generate or update the documentation changelog:

### Step 1: Determine the date range

1. Check if `documentation/changelog.mdx` exists
2. If it exists, parse the most recent date header (format: `## YYYY-MM-DD` or `## Month YYYY`)
3. If no changelog exists or no date found, use 1 month ago from today. No exceptions
4. If existing changelog: use the last entry date
5. NEVER go further back than the calculated date, even if you see interesting commits
6. If asked to go further back, confirm with the user first
7. Store this as `SINCE_DATE`

### Step 2: Get commits since that date

Run:
```bash
git log --since="$SINCE_DATE" --pretty=format:"%H|%ad|%s" --date=short --no-merges -- documentation/
```

### Step 2b: Get QuestDB releases for the period

Fetch releases from the QuestDB GitHub repository:
```bash
gh api repos/questdb/questdb/releases --jq '.[] | "\(.tag_name)|\(.published_at)"'
```

Filter releases that fall within the changelog period. Group by month.

**Format for releases:**
```markdown
### Releases

- [9.3.2](https://questdb.com/release-notes/) - Released January 28, 2026
- [9.3.1](https://questdb.com/release-notes/) - Released January 14, 2026
```

**Rules:**
- Include ALL releases in the period, one line per release
- Link text is the version number (e.g., `9.3.2`)
- All links point to `https://questdb.com/release-notes/`
- Include the release date in format "Released Month DD, YYYY"
- List releases in descending order (newest first)
- Place the "Releases" section FIRST in each month's entry (before "New", "Updated", etc.)
- If no releases in a month, omit the "Releases" section entirely

### Step 3: Analyze each commit

For each commit hash, get the diff:
```bash
git show <hash> --stat --no-color -- '*.md' '*.mdx'
git diff <hash>^..<hash> -- '*.md' '*.mdx'
```

Classify changes into:

**SKIP (cosmetic/internal):**
- Typo fixes (< 5 words changed)
- Whitespace/formatting only
- Navigation/sidebar changes only
- Internal link updates
- CI/build config changes
- README updates (unless user-facing)

**INCLUDE (user-facing):**
- New documentation pages
- New sections in existing pages
- Updated code examples
- API reference changes
- New SQL function docs
- Configuration option docs
- Tutorial additions/updates
- Corrected technical instructions

### Step 4: Categorize included changes

Group by:
- **Releases** — QuestDB releases in this period (from Step 2b)
- **New** — Brand new pages or major new sections
- **Updated** — Significant updates to existing content
- **Reference** — SQL functions, configuration, API docs
- **Guides** — Tutorials, how-tos, walkthroughs

### Step 5: Generate changelog entry

Format for Docusaurus:
```mdx
## February 2026

### Releases

- [9.4.0](https://questdb.com/release-notes/) - Released February 15, 2026

### New

- [TICK Syntax](/docs/query/operators/tick/) - New DSL for expressing complex time intervals
- [Database Views](/docs/concepts/views/) - Virtual tables for query composition

### Updated

- [Materialized Views](/docs/concepts/materialized-views/) - Added `REFRESH PERIOD` compact syntax
- [Window Functions](/docs/query/functions/window-functions/overview/) - Now support arithmetic expressions

### Reference

- Added `weighted_avg()`, `weighted_stddev_rel()`, `weighted_stddev_freq()` functions
- Documented `tables()` system view columns: `minTimestamp`, `maxTimestamp`
```

### Link Validation (BEFORE writing)

1. Before generating any internal link, verify the target file exists:
```bash
# Check if the page exists
ls documentation/reference/sql/tick.mdx 2>/dev/null || echo "NOT FOUND"
```

2. If the file doesn't exist, use ONE of these strategies:
- Option A: Describe without linking (preferred for speed)
"Added TICK syntax documentation for time intervals"
- Option B: Use a search-friendly description
"TICK Syntax (see SQL Reference > TICK)"

3. NEVER generate a markdown link unless you've confirmed the path exists

4. For sidebar links, check sidebars.js or the actual file structure first

### Validation Strategy (FAST)

1. DO NOT run `yarn build` to validate links during iteration
2. Instead, validate links by checking the filesystem directly:
```bash
# Get all .md and .mdx files and their paths
find documentation -name "*.mdx" -o -name "*.md" | sed 's|documentation/||; s|\.mdx$||; s|\.md$||'
```

3. Cross-reference your generated links against this list BEFORE writing
4. Only run a build check ONCE at the very end, after all content is finalized
5. If build fails, fix ALL broken links in one pass, not iteratively

### Step 6: Update the changelog file

Prepend the new entry after the frontmatter but before existing entries.

The changelog file location is `documentation/changelog.mdx` (NOT `documentation/docs/changelog.mdx`).

---

## One-Shot Prompt for Claude Code

Here's a prompt you can paste directly into Claude Code:
```
Generate a documentation changelog for the QuestDB docs.

1. First, check if documentation/changelog.mdx exists. If so, find the date of the most recent entry. If not, we'll create it and use 1 month ago as the start date.

2. Get all commits to .md and .mdx files since that date:
git log --since="<date>" --pretty=format:"%H|%ad|%s" --date=short --no-merges -- 'documentation/**/*.md' 'documentation/**/*.mdx'

3. Get QuestDB releases for the period:
gh api repos/questdb/questdb/releases --jq '.[] | "\(.tag_name)|\(.published_at)"'

4. For each commit, examine the diff to determine if it's user-facing:
- SKIP: typos, formatting, nav changes, link fixes, build/CI changes
- INCLUDE: new pages, new sections, updated examples, API docs, config docs, corrected instructions

5. For included changes, write a one-line summary describing what users will find different. Focus on the benefit, not the file path.

6. Group changes into: Releases (from GitHub), New, Updated, Reference, Guides

7. Format as a Docusaurus-compatible MDX entry with the month/year as header.

8. Either create documentation/changelog.mdx with proper frontmatter, or prepend the new entry to the existing file.

Be concise in summaries. Users want to know "what can I learn that I couldn't before" not "file X was modified."
```
155 changes: 155 additions & 0 deletions documentation/changelog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
---
title: Documentation changelog
sidebar_label: Changelog
description: Recent updates and improvements to the QuestDB documentation.
---

# Documentation changelog

This page tracks significant updates to the QuestDB documentation.

## January 2026

### Releases

- [9.3.2](https://questdb.com/release-notes/) - Released January 28, 2026
- [9.3.1](https://questdb.com/release-notes/) - Released January 14, 2026
- [9.3.0](https://questdb.com/release-notes/) - Released January 9, 2026

### New

- [Cookbook](/docs/cookbook/) - Collection of 40+ recipes for common SQL patterns, integrations, and operations
- Capital markets recipes - Financial calculations including VWAP, Bollinger Bands, TICK/TRIN, volume analysis, and more
- [TICK syntax](/docs/query/operators/tick/) - New DSL for expressing time intervals with intuitive syntax like `'$now - 1h..$now'`
- [AI Assistant reference](/docs/getting-started/web-console/questdb-ai/) - Documentation for the QuestDB AI Assistant
- [PIVOT](/docs/query/sql/pivot/) - SQL keyword for rotating rows into columns

### Updated

- [Window functions](/docs/query/functions/window-functions/overview/) - Restructured into dedicated section with improved navigation, added EMA, VWEMA, and ksum() functions
- [Views and materialized views](/docs/concepts/views/) - Comprehensive documentation overhaul with improved examples and clearer explanations
- [Designated timestamp](/docs/concepts/designated-timestamp/) - Consolidated timestamp documentation with TICK syntax examples
- [Enterprise backup](/docs/operations/backup/) - Improved documentation with clearer instructions

### Reference

- Added [`percent_rank()`](/docs/query/functions/window-functions/reference/#percent_rank) window function
- Added [`arg_min()`](/docs/query/functions/aggregation/#arg_min) and [`arg_max()`](/docs/query/functions/aggregation/#arg_max) aggregation functions
- Added [`length_bytes()`](/docs/query/functions/text/#length_bytes) function for byte-length of strings
- Added [`rnd_symbol_zipf()`](/docs/query/functions/random-value-generator/#rnd_symbol_zipf) and weighted random generators
- Added [Euclidean and geographic geo functions](/docs/query/functions/spatial/)
- Extended [date arithmetic](/docs/query/operators/tick/) with sub-day units

## December 2025

### Releases

- [9.2.3](https://questdb.com/release-notes/) - Released December 18, 2025
- [9.2.2](https://questdb.com/release-notes/) - Released December 1, 2025

### New

- [Builtin profiler](/docs/troubleshooting/profiling/) - Documentation for QuestDB's built-in query profiler
- [WINDOW JOIN](/docs/query/sql/window-join/) - SQL reference for window joins with time-based lookups

### Updated

- [Materialized views](/docs/concepts/materialized-views/) - Added `REFRESH PERIOD (SAMPLE BY INTERVAL)` compact syntax documentation
- [Time-series optimizations](/docs/architecture/time-series-optimizations/) - Improved explanations

### Reference

- Added [`weighted_avg()`](/docs/query/functions/aggregation/#weighted_avg), [`weighted_stddev_rel()`](/docs/query/functions/aggregation/#weighted_stddev_rel), [`weighted_stddev_freq()`](/docs/query/functions/aggregation/#weighted_stddev_freq) functions
- Documented compact period syntax in [SAMPLE BY](/docs/query/sql/sample-by/)

## November 2025

### Releases

- [9.2.1](https://questdb.com/release-notes/) - Released November 25, 2025
- [9.2.0](https://questdb.com/release-notes/) - Released November 13, 2025
- [9.1.1](https://questdb.com/release-notes/) - Released November 3, 2025

### New

- [Hetzner deployment](/docs/deployment/hetzner/) - Step-by-step guide for deploying QuestDB on Hetzner Cloud
- [DECIMAL datatype](/docs/query/datatypes/decimal/) - Documentation for precise decimal arithmetic
- [PGWire OIDC integration](/docs/security/oidc/) - Authentication via OpenID Connect

### Updated

- [Parquet export](/docs/query/export-parquet/) - Complete documentation for exporting data to Parquet format
- [Shared pool configuration](/docs/configuration/overview/#shared-worker) - Updated with network, query, and write shared pool options
- [SQL hints](/docs/query/sql/asof-join/#choose-the-optimal-algorithm-with-an-sql-hint) - Rewritten section on temporal join hints

### Reference

- Added `first()` and `last()` support for additional datatypes
- Added `first_not_null()` and `last_not_null()` array support

## October 2025

### Releases

- [9.1.0](https://questdb.com/release-notes/) - Released October 3, 2025

### New

- [PGWire for C/C++](/docs/query/pgwire/c-and-cpp/) - Guide for C/C++ applications using PostgreSQL wire protocol
- [Table and column naming rules](/docs/query/sql/create-table/#table-name) - Guidelines for valid identifiers

### Updated

- [Architecture guide](/docs/architecture/questdb-architecture/) - Refreshed with current implementation details
- [Nanoseconds](/docs/query/datatypes/overview/#timestamp-and-date-considerations) - Added nanosecond timestamp precision documentation
- [`TRUNCATE TABLE`](/docs/query/sql/truncate/) - Added `IF EXISTS` clause

### Reference

- Added `w` (week) unit to [SAMPLE BY](/docs/query/sql/sample-by/) reference

## September 2025

### Updated

- [Partitioning](/docs/concepts/partitions/) - Improved formatting and explanations
- [Go client examples](/docs/ingestion/clients/go/) - Updated to v4 API

## August 2025

### Releases

- [9.0.3](https://questdb.com/release-notes/) - Released August 29, 2025
- [9.0.2](https://questdb.com/release-notes/) - Released August 15, 2025

### New

- [Array functions](/docs/query/functions/array/) - Documentation for array manipulation functions

### Updated

- [`to_timestamp()`](/docs/query/functions/date-time/#to_timestamp) - Improved documentation with more examples
- [Web Console](/docs/getting-started/web-console/overview/) - Updated documentation for latest console features

## July 2025

### Releases

- [9.0.1](https://questdb.com/release-notes/) - Released July 23, 2025
- [9.0.0](https://questdb.com/release-notes/) - Released July 11, 2025

### New

- [N-dimensional arrays](/docs/query/datatypes/array/) - Comprehensive guide to multi-dimensional arrays
- [Order book analytics](/docs/tutorials/order-book/) - Guide for processing order book data
- [Period materialized views](/docs/concepts/materialized-views/#period-refresh) - Time-based refresh for materialized views
- [ASOF JOIN TOLERANCE](/docs/query/sql/asof-join/#tolerance-clause) - Limit lookback window in temporal joins

### Updated

- [ILP clients](/docs/ingestion/overview/) - Array support added to Python, C++, Rust, Java, and .NET clients
- [WAL metrics](/docs/operations/monitoring-alerting/) - Added metrics for detecting WAL apply lag

## Earlier updates

For documentation changes before July 2025, see the [git commit history](https://github.com/questdb/questdb.io/commits/main/documentation).
3 changes: 2 additions & 1 deletion documentation/sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -905,8 +905,9 @@ module.exports = {
},

// ===================
// RELEASE NOTES
// CHANGELOG & RELEASE NOTES
// ===================
"changelog",
{
label: "Release Notes",
type: "link",
Expand Down