holetron-lab/fleet-memory
1
0
Fork 0
Code Releases Packages Activity Actions

fix(doc): improve docs versioning and release (#231)

Browse source 
* fix(doc): improve docs versioning and release

* fix(doc): improve docs versioning and release
This commit is contained in:
Nicolò Boschi 2026-01-29 14:45:57 +01:00 committed by GitHub
parent b8f06a09fb
commit a7c094d436
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 165 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
hindsight-docs/versioned_docs/version-0.4/developer/configuration.md
View file

@ -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

43
scripts/bump-docs-version.sh
View file

@ -1,43 +0,0 @@
#!/bin/bash
set -e
# Bump documentation version for Docusaurus
# Usage: ./scripts/bump-docs-version.sh <version>
# 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 <version>"
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"

32
scripts/release.sh
View file

@ -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"

113
scripts/update-docs-version.sh Executable file
View file

@ -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 <version>
# 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 <version>"
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"

10
uv.lock
View file

@ -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" },