Skip to content

Commit 0e9fd70

Browse files
prmoore77claude
prmoore77
and
claude
committed
docs: refresh Quick Start to v1.28.0 + auto-sync version on release
- Update example server banner and GIZMOSQL_VERSION() output to v1.28.0 - Add a note that starting a second server on the default port 31337 fails with "address already in use", with the --port workaround - Add scripts/update_docs_version.sh to rewrite the example version - Add a sync-docs-version CI job that runs it on every tag push, commits to main, and redeploys the docs site Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 1e7ed70 commit 0e9fd70

4 files changed

Lines changed: 98 additions & 2 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -914,6 +914,47 @@ jobs:
914914
artifacts/GizmoSQL-*.msi
915915
LICENSE
916916
917+
sync-docs-version:
918+
name: Sync Quick Start docs version
919+
if: startsWith(github.ref, 'refs/tags/v')
920+
needs: create-release
921+
runs-on: ubuntu-latest
922+
permissions:
923+
contents: write
924+
actions: write
925+
steps:
926+
- name: Checkout main
927+
uses: actions/checkout@v6
928+
with:
929+
ref: main
930+
fetch-depth: 0
931+
932+
- name: Update example version in docs/quickstart.md
933+
run: ./scripts/update_docs_version.sh "${{ github.ref_name }}"
934+
935+
- name: Commit and push if changed
936+
id: commit
937+
run: |
938+
git config user.name "github-actions[bot]"
939+
git config user.email "github-actions[bot]@users.noreply.github.com"
940+
if git diff --quiet -- docs/quickstart.md; then
941+
echo "Docs already on ${{ github.ref_name }}; nothing to do."
942+
echo "changed=false" >> "$GITHUB_OUTPUT"
943+
else
944+
git add docs/quickstart.md
945+
git commit -m "docs: sync Quick Start example version to ${{ github.ref_name }}"
946+
git push origin main
947+
echo "changed=true" >> "$GITHUB_OUTPUT"
948+
fi
949+
950+
# A push made with GITHUB_TOKEN does not trigger other workflows, so
951+
# explicitly dispatch the docs deploy to publish the updated version.
952+
- name: Trigger docs deploy
953+
if: steps.commit.outputs.changed == 'true'
954+
env:
955+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
956+
run: gh workflow run deploy-docs.yml --ref main
957+
917958
update-image-manifest:
918959
name: Merge per-platform images into multi-arch manifests (with attestations)
919960
if: startsWith(github.ref, 'refs/tags/')

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- **Quick Start docs now auto-track the latest release.** The example server-startup banner and `GIZMOSQL_VERSION()` output in `docs/quickstart.md` are rewritten to the released version by `scripts/update_docs_version.sh`, run by a new `sync-docs-version` CI job on every tag push (which commits the update to `main` and redeploys the docs site). The Quick Start also now notes that starting a second server on the default port `31337` fails with an "address already in use" error, and how to pick a different `--port`.
13+
14+
### Changed
15+
16+
- Updated the Quick Start example version strings from `v1.25.1` to `v1.28.0`.
17+
1018
## [1.28.0] - 2026-06-03
1119

1220
### Added

‎docs/quickstart.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,11 @@ GIZMOSQL_PASSWORD=tiger gizmosql_server --username scott
4040
You'll see a startup banner ending in something like:
4141

4242
```
43-
INFO ... GizmoSQL server version: v1.25.1 - with engine: DuckDB - will listen on grpc+tcp://0.0.0.0:31337
43+
INFO ... GizmoSQL server version: v1.28.0 - with engine: DuckDB - will listen on grpc+tcp://0.0.0.0:31337
4444
```
4545

46+
> **Already have a server running?** GizmoSQL binds port `31337` by default, so if another GizmoSQL instance (or anything else) is already listening there, startup fails with an "address already in use" / bind error instead of starting. Stop the other server, or pick a different port with `--port 31338` (and pass the same `--port` to `gizmosql_client` when you connect).
47+
4648
Want to persist data? Add `--database-filename my_database.duckdb`. For TLS, see the [Security Guide](security.md).
4749

4850
> **Tip:** GizmoSQL is happy as a long-running shared SQL server, an embedded process inside an app, or [a mobile app on iOS](https://apps.apple.com/us/app/gizmosql/id6761951280). Same protocol, same query layer.
@@ -68,7 +70,7 @@ SELECT GIZMOSQL_VERSION(), GIZMOSQL_EDITION();
6870
│ GIZMOSQL_VERSION() │ GIZMOSQL_EDITION() │
6971
│ varchar │ varchar │
7072
├────────────────────┼────────────────────┤
71-
│ v1.25.1 │ Core │
73+
│ v1.28.0 │ Core │
7274
├────────────────────┴────────────────────┤
7375
│ 1 row 2 columns │
7476
└─────────────────────────────────────────┘

‎scripts/update_docs_version.sh‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
#!/usr/bin/env bash
2+
#
3+
# update_docs_version.sh — Sync the example GizmoSQL version strings in the
4+
# Quick Start docs (docs/quickstart.md) to the latest released version.
5+
#
6+
# These are illustrative output snippets (the server startup banner and the
7+
# GIZMOSQL_VERSION() result), so they should always reflect the current
8+
# release. This script is run automatically by the `sync-docs-version` CI job
9+
# on every tag push, and can also be run by hand:
10+
#
11+
# scripts/update_docs_version.sh # uses the latest git tag
12+
# scripts/update_docs_version.sh v1.28.0 # explicit version
13+
#
14+
# It only rewrites the version token in two well-known lines, so it is safe to
15+
# re-run and idempotent.
16+
set -euo pipefail
17+
18+
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
19+
QUICKSTART="${REPO_ROOT}/docs/quickstart.md"
20+
21+
# Resolve the target version: explicit arg, else the latest git tag.
22+
VERSION="${1:-$(git -C "${REPO_ROOT}" describe --tags --abbrev=0)}"
23+
VERSION="v${VERSION#v}" # normalize so both "1.28.0" and "v1.28.0" work
24+
25+
if [[ ! "${VERSION}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
26+
echo "error: '${VERSION}' is not a vMAJOR.MINOR.PATCH version" >&2
27+
exit 1
28+
fi
29+
30+
# 1. Server startup banner: "GizmoSQL server version: vX.Y.Z - with engine..."
31+
sed -i.bak -E \
32+
"s|(GizmoSQL server version: )v[0-9]+\.[0-9]+\.[0-9]+|\1${VERSION}|" \
33+
"${QUICKSTART}"
34+
35+
# 2. GIZMOSQL_VERSION() result cell. The column is 18 chars wide and
36+
# left-aligned (1 leading + 1 trailing space inside the 20-wide box cell),
37+
# so regenerate the whole line with printf to keep the box drawing aligned.
38+
CELL="$(printf '%-18s' "${VERSION}")"
39+
sed -i.bak -E \
40+
"s|^│ v[0-9]+\.[0-9]+\.[0-9]+ +│ Core │$|│ ${CELL} │ Core │|" \
41+
"${QUICKSTART}"
42+
43+
rm -f "${QUICKSTART}.bak"
44+
45+
echo "Updated ${QUICKSTART#${REPO_ROOT}/} to ${VERSION}"

0 commit comments

Comments
 (0)