From a7c094d43624ef14fd5dd01d939921058b923fb5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Thu, 29 Jan 2026 14:45:57 +0100 Subject: [PATCH] fix(doc): improve docs versioning and release (#231) * fix(doc): improve docs versioning and release * fix(doc): improve docs versioning and release --- .../version-0.4/developer/configuration.md | 16 +++ scripts/bump-docs-version.sh | 43 ------- scripts/release.sh | 32 ++++- scripts/update-docs-version.sh | 113 ++++++++++++++++++ uv.lock | 10 +- 5 files changed, 165 insertions(+), 49 deletions(-) delete mode 100755 scripts/bump-docs-version.sh create mode 100755 scripts/update-docs-version.sh diff --git a/hindsight-docs/versioned_docs/version-0.4/developer/configuration.md b/hindsight-docs/versioned_docs/version-0.4/developer/configuration.md index f534397e..f646413e 100644 --- a/hindsight-docs/versioned_docs/version-0.4/developer/configuration.md +++ b/hindsight-docs/versioned_docs/version-0.4/developer/configuration.md @@ -20,10 +20,24 @@ The API service handles all memory operations (retain, recall, reflect). | Variable | Description | Default | |----------|-------------|---------| | `HINDSIGHT_API_DATABASE_URL` | PostgreSQL connection string | `pg0` (embedded) | +| `HINDSIGHT_API_DATABASE_SCHEMA` | PostgreSQL schema name for tables | `public` | | `HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUP` | Run database migrations on API startup | `true` | If not provided, the server uses embedded `pg0` — convenient for development but not recommended for production. +The `DATABASE_SCHEMA` setting allows you to use a custom PostgreSQL schema instead of the default `public` schema. This is useful for: +- Multi-database setups where you want Hindsight tables in a dedicated schema +- Hosting platforms (e.g., Supabase) where `public` schema is reserved or shared +- Organizational preferences for schema naming conventions + +```bash +# Example: Using a custom schema +export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@host:5432/dbname +export HINDSIGHT_API_DATABASE_SCHEMA=hindsight +``` + +Migrations will automatically create the schema if it doesn't exist and create all tables in the configured schema. + ### Database Connection Pool | Variable | Description | Default | @@ -364,6 +378,7 @@ Observations are consolidated knowledge synthesized from facts. |----------|-------------|---------| | `HINDSIGHT_API_ENABLE_OBSERVATIONS` | Enable observation consolidation | `true` | | `HINDSIGHT_API_CONSOLIDATION_BATCH_SIZE` | Memories to load per batch (internal optimization) | `50` | +| `HINDSIGHT_API_CONSOLIDATION_MAX_TOKENS` | Max tokens for recall when finding related observations during consolidation | `1024` | | `HINDSIGHT_API_RETAIN_OBSERVATIONS_ASYNC` | Run observation generation asynchronously (after retain completes) | `false` | ### Reflect @@ -439,6 +454,7 @@ export HINDSIGHT_CP_DATAPLANE_API_URL=http://api.example.com:8888 ```bash # API Service HINDSIGHT_API_DATABASE_URL=postgresql://hindsight:hindsight_dev@localhost:5432/hindsight +# HINDSIGHT_API_DATABASE_SCHEMA=public # optional, defaults to 'public' HINDSIGHT_API_LLM_PROVIDER=groq HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx diff --git a/scripts/bump-docs-version.sh b/scripts/bump-docs-version.sh deleted file mode 100755 index 79b6b88b..00000000 --- a/scripts/bump-docs-version.sh +++ /dev/null @@ -1,43 +0,0 @@ -#!/bin/bash -set -e - -# Bump documentation version for Docusaurus -# Usage: ./scripts/bump-docs-version.sh -# Example: ./scripts/bump-docs-version.sh 0.4 - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -ROOT_DIR="$(dirname "$SCRIPT_DIR")" -DOCS_DIR="$ROOT_DIR/hindsight-docs" - -if [ -z "$1" ]; then - echo "Usage: $0 " - echo "Example: $0 0.4" - exit 1 -fi - -VERSION="$1" - -# Validate version format (minor version only: X.Y) -if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+$ ]]; then - echo "Error: Version must be in format X.Y (e.g., 0.4)" - exit 1 -fi - -echo "Creating docs version $VERSION..." - -# Create the version snapshot -cd "$DOCS_DIR" -npx docusaurus docs:version "$VERSION" - -echo "" -echo "Done! Version $VERSION created." -echo "" -echo "Files created/modified:" -echo " - versioned_docs/version-$VERSION/" -echo " - versioned_sidebars/version-$VERSION-sidebars.json" -echo " - versions.json (automatically read by docusaurus.config.ts)" -echo "" -echo "Next steps:" -echo " 1. Review the changes" -echo " 2. Test with: cd hindsight-docs && npm run build" -echo " 3. Commit the versioned docs" diff --git a/scripts/release.sh b/scripts/release.sh index ad9faa17..ae00d080 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -144,6 +144,19 @@ else print_warn "File $TYPESCRIPT_CLIENT_PKG not found, skipping" fi +# Update documentation version (creates new version or syncs to existing) +print_info "Updating documentation for version $VERSION..." +if [ -f "scripts/update-docs-version.sh" ]; then + ./scripts/update-docs-version.sh "$VERSION" 2>&1 | grep -E "✓|IMPORTANT|Error" || true + if [ ${PIPESTATUS[0]} -eq 0 ]; then + print_info "✓ Documentation updated" + else + print_warn "Failed to update documentation, but continuing..." + fi +else + print_warn "update-docs-version.sh not found, skipping docs update" +fi + # Show changes print_info "Changes to be committed:" git diff @@ -161,7 +174,13 @@ fi # Commit changes print_info "Committing version changes..." git add -A -git commit --no-verify -m "Release v$VERSION + +# Extract major.minor and patch for commit message +MAJOR_MINOR=$(echo "$VERSION" | sed -E 's/^([0-9]+\.[0-9]+)\.[0-9]+$/\1/') +PATCH_VERSION=$(echo "$VERSION" | sed -E 's/^[0-9]+\.[0-9]+\.([0-9]+)$/\1/') + +# Build commit message +COMMIT_MSG="Release v$VERSION - Update version to $VERSION in all components - Python packages: hindsight-api, hindsight-dev, hindsight-all, hindsight-litellm, hindsight-embed @@ -171,6 +190,17 @@ git commit --no-verify -m "Release v$VERSION - Control Plane: hindsight-control-plane - Helm chart" +# Add docs update note +if [ "$PATCH_VERSION" != "0" ]; then + COMMIT_MSG="$COMMIT_MSG +- Sync documentation to version-$MAJOR_MINOR" +else + COMMIT_MSG="$COMMIT_MSG +- Create documentation version-$MAJOR_MINOR" +fi + +git commit --no-verify -m "$COMMIT_MSG" + # Create tag print_info "Creating tag v$VERSION..." git tag -a "v$VERSION" -m "Release v$VERSION" diff --git a/scripts/update-docs-version.sh b/scripts/update-docs-version.sh new file mode 100755 index 00000000..ecf61fa9 --- /dev/null +++ b/scripts/update-docs-version.sh @@ -0,0 +1,113 @@ +#!/bin/bash +set -e + +# Unified docs versioning script for Docusaurus +# Automatically handles both patch releases (sync) and minor/major releases (create new version) +# +# Usage: ./scripts/update-docs-version.sh +# Examples: +# ./scripts/update-docs-version.sh 0.4.2 # Patch: syncs docs/ to existing version-0.4/ +# ./scripts/update-docs-version.sh 0.5.0 # Minor: creates new version-0.5/ snapshot + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT_DIR="$(dirname "$SCRIPT_DIR")" +DOCS_DIR="$ROOT_DIR/hindsight-docs" + +# Colors for output +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' + +print_info() { + echo -e "${GREEN}[INFO]${NC} $1" +} + +print_warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +if [ -z "$1" ]; then + echo "Usage: $0 " + echo "" + echo "Examples:" + echo " $0 0.4.2 # Patch release: syncs docs/ to version-0.4/" + echo " $0 0.5.0 # Minor release: creates new version-0.5/" + exit 1 +fi + +VERSION="$1" + +# Validate version format (semantic versioning) +if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "Error: Version must be in X.Y.Z format (e.g., 0.4.2 or 0.5.0)" + exit 1 +fi + +# Extract major.minor and patch version +MAJOR_MINOR=$(echo "$VERSION" | sed -E 's/^([0-9]+\.[0-9]+)\.[0-9]+$/\1/') +PATCH_VERSION=$(echo "$VERSION" | sed -E 's/^[0-9]+\.[0-9]+\.([0-9]+)$/\1/') + +SOURCE_DIR="$DOCS_DIR/docs" +TARGET_DIR="$DOCS_DIR/versioned_docs/version-${MAJOR_MINOR}" +VERSIONS_FILE="$DOCS_DIR/versions.json" + +# Determine action based on patch version +if [ "$PATCH_VERSION" != "0" ]; then + # + # PATCH RELEASE: Sync docs to existing version + # + print_info "Detected PATCH release ($VERSION)" + print_info "Syncing docs/ → versioned_docs/version-${MAJOR_MINOR}/" + + if [ ! -d "$TARGET_DIR" ]; then + echo "Error: Target version directory does not exist: $TARGET_DIR" + echo "" + echo "Available versions:" + [ -f "$VERSIONS_FILE" ] && cat "$VERSIONS_FILE" || echo " (No versions.json found)" + exit 1 + fi + + # Use rsync to sync, preserving structure and deleting removed files + rsync -av --delete \ + --exclude='*.swp' \ + --exclude='.DS_Store' \ + "$SOURCE_DIR/" "$TARGET_DIR/" + + echo "" + print_info "✓ Synced docs/ to version-${MAJOR_MINOR}" + print_info "✓ Files updated in: $TARGET_DIR" + +else + # + # MINOR/MAJOR RELEASE: Create new version snapshot + # + print_info "Detected MINOR/MAJOR release ($VERSION)" + print_info "Creating new docs version: version-${MAJOR_MINOR}" + + # Check if version already exists + if [ -d "$TARGET_DIR" ]; then + echo "Error: Version $MAJOR_MINOR already exists in $TARGET_DIR" + echo "If you want to update it, use a patch version (e.g., ${MAJOR_MINOR}.1)" + exit 1 + fi + + # Create the version snapshot using Docusaurus + cd "$DOCS_DIR" + npx docusaurus docs:version "$MAJOR_MINOR" + + echo "" + print_info "✓ Created docs version-${MAJOR_MINOR}" + print_info "Files created:" + print_info " - versioned_docs/version-${MAJOR_MINOR}/" + print_info " - versioned_sidebars/version-${MAJOR_MINOR}-sidebars.json" + print_info " - versions.json (updated)" + echo "" + print_warn "IMPORTANT: Future docs changes will go to docs/ (next version)" + print_warn " To update ${MAJOR_MINOR} docs, use patch releases (e.g., ${MAJOR_MINOR}.1)" +fi + +echo "" +print_info "Next steps:" +echo " 1. Review changes: git diff $DOCS_DIR" +echo " 2. Test build: cd hindsight-docs && npm run build" +echo " 3. Changes will be committed automatically by release.sh" diff --git a/uv.lock b/uv.lock index a849e20c..2c6bb090 100644 --- a/uv.lock +++ b/uv.lock @@ -1295,7 +1295,7 @@ wheels = [ [[package]] name = "hindsight-all" -version = "0.4.0" +version = "0.4.1" source = { editable = "hindsight" } dependencies = [ { name = "hindsight-api" }, @@ -1319,7 +1319,7 @@ provides-extras = ["test"] [[package]] name = "hindsight-api" -version = "0.4.0" +version = "0.4.1" source = { editable = "hindsight-api" } dependencies = [ { name = "aiohttp" }, @@ -1447,7 +1447,7 @@ dev = [ [[package]] name = "hindsight-client" -version = "0.4.0" +version = "0.4.1" source = { editable = "hindsight-clients/python" } dependencies = [ { name = "aiohttp" }, @@ -1481,7 +1481,7 @@ provides-extras = ["test"] [[package]] name = "hindsight-dev" -version = "0.4.0" +version = "0.4.1" source = { editable = "hindsight-dev" } dependencies = [ { name = "hindsight-api" }, @@ -1527,7 +1527,7 @@ dev = [ [[package]] name = "hindsight-embed" -version = "0.4.0" +version = "0.4.1" source = { editable = "hindsight-embed" } dependencies = [ { name = "httpx" },