From 123f871659c47b8de853411416995e61bea5743e Mon Sep 17 00:00:00 2001 From: javier Date: Wed, 4 Feb 2026 12:22:46 +0100 Subject: [PATCH] Add documentation changelog page - Add changelog.mdx tracking documentation updates from July 2025 to January 2026 - Include QuestDB releases for each month - Add sidebar entry for changelog - Add claude_changelog.md with instructions for generating future updates --- claude_changelog.md | 177 ++++++++++++++++++++++++++++++++++++ documentation/changelog.mdx | 155 +++++++++++++++++++++++++++++++ documentation/sidebars.js | 3 +- 3 files changed, 334 insertions(+), 1 deletion(-) create mode 100644 claude_changelog.md create mode 100644 documentation/changelog.mdx diff --git a/claude_changelog.md b/claude_changelog.md new file mode 100644 index 000000000..26c599c00 --- /dev/null +++ b/claude_changelog.md @@ -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 --stat --no-color -- '*.md' '*.mdx' +git diff ^.. -- '*.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="" --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." +``` diff --git a/documentation/changelog.mdx b/documentation/changelog.mdx new file mode 100644 index 000000000..df2719a7d --- /dev/null +++ b/documentation/changelog.mdx @@ -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). diff --git a/documentation/sidebars.js b/documentation/sidebars.js index b39f153f3..f29a37f4c 100644 --- a/documentation/sidebars.js +++ b/documentation/sidebars.js @@ -905,8 +905,9 @@ module.exports = { }, // =================== - // RELEASE NOTES + // CHANGELOG & RELEASE NOTES // =================== + "changelog", { label: "Release Notes", type: "link",