Updated all README files in the
helper-scripts directory to: 1. Main helper-scripts/README.md: Updated to describe generate-release-notes.js instead of the old bash script, including new configuration options and examples. 2. helper-scripts/common/README.md: Updated to describe the JavaScript version with all its new features like configuration files, integrated/separated formats, and PR link options. 3. helper-scripts/influxdb3-monolith/RE ADME.md: Completely updated to reflect the actual JavaScript scripts present (audit-cli-documentation.js and apply-cli-patches.js) instead of the non-existent bash scripts, updated prerequisites, examples, and workflow documentation.pull/6190/head
Jason Stirnaman
parent
ff04be05ed
commit
105938f3aa
|
|
@ -59,11 +59,9 @@ jobs:
|
|||
# (influxdb and influxdb_pro) are not available in the GitHub Actions environment.
|
||||
# To generate actual release notes, the script would need to be run locally with:
|
||||
# node ./helper-scripts/common/generate-release-notes.js \
|
||||
# --format core-enterprise \
|
||||
# --config ./helper-scripts/common/config/influxdb3-core-enterprise.json \
|
||||
# ${{ github.event.inputs.previous_version }} \
|
||||
# ${{ github.event.inputs.version }} \
|
||||
# /path/to/influxdb \
|
||||
# /path/to/influxdb_pro
|
||||
# ${{ github.event.inputs.version }}
|
||||
|
||||
# Create structured placeholder that matches the expected format
|
||||
cat > helper-scripts/output/release-notes/release-notes-${{ github.event.inputs.product }}-${{ github.event.inputs.version }}.md << EOF
|
||||
|
|
@ -108,67 +106,66 @@ jobs:
|
|||
path: helper-scripts/output/release-notes/
|
||||
retention-days: 30
|
||||
|
||||
generate-release-notes-distributed:
|
||||
name: Generate Release Notes (Distributed)
|
||||
runs-on: ubuntu-latest
|
||||
if: contains(fromJSON('["clustered", "cloud-dedicated", "cloud-serverless"]'), github.event.inputs.product)
|
||||
outputs:
|
||||
generated: ${{ steps.generate.outputs.generated }}
|
||||
# generate-release-notes-distributed:
|
||||
# name: Generate Release Notes (Distributed)
|
||||
# runs-on: ubuntu-latest
|
||||
# if: contains(fromJSON('["clustered", "cloud-dedicated", "cloud-serverless"]'), github.event.inputs.product)
|
||||
# outputs:
|
||||
# generated: ${{ steps.generate.outputs.generated }}
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
# steps:
|
||||
# - uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '18'
|
||||
cache: 'yarn'
|
||||
# - name: Set up Node.js
|
||||
# uses: actions/setup-node@v4
|
||||
# with:
|
||||
# node-version: '18'
|
||||
# cache: 'yarn'
|
||||
|
||||
- name: Install dependencies
|
||||
run: yarn install --frozen-lockfile
|
||||
# - name: Install dependencies
|
||||
# run: yarn install --frozen-lockfile
|
||||
|
||||
- name: Generate release notes
|
||||
id: generate
|
||||
run: |
|
||||
echo "Generating distributed product release notes for ${{ github.event.inputs.product }} v${{ github.event.inputs.version }}"
|
||||
# - name: Generate release notes
|
||||
# id: generate
|
||||
# run: |
|
||||
# echo "Generating distributed product release notes for ${{ github.event.inputs.product }} v${{ github.event.inputs.version }}"
|
||||
|
||||
# Create output directory
|
||||
mkdir -p helper-scripts/output/release-notes
|
||||
# # Create output directory
|
||||
# mkdir -p helper-scripts/output/release-notes
|
||||
|
||||
# Note: This generates placeholder release notes since the actual repositories
|
||||
# for distributed products are not available in the GitHub Actions environment.
|
||||
# To generate actual release notes, the script would need to be run locally with:
|
||||
# node ./helper-scripts/common/generate-release-notes.js \
|
||||
# --format standard \
|
||||
# ${{ github.event.inputs.previous_version }} \
|
||||
# ${{ github.event.inputs.version }} \
|
||||
# /path/to/repository
|
||||
# # Note: This generates placeholder release notes since the actual repositories
|
||||
# # for distributed products are not available in the GitHub Actions environment.
|
||||
# # To generate actual release notes, the script would need to be run locally with:
|
||||
# # node ./helper-scripts/common/generate-release-notes.js \
|
||||
# # --config ./helper-scripts/common/config/influxdb3-clustered.json \
|
||||
# # ${{ github.event.inputs.previous_version }} \
|
||||
# # ${{ github.event.inputs.version }}
|
||||
|
||||
# Create structured placeholder for distributed products
|
||||
cat > helper-scripts/output/release-notes/release-notes-${{ github.event.inputs.product }}-${{ github.event.inputs.version }}.md << EOF
|
||||
## ${{ github.event.inputs.version }} {date="$(date +'%Y-%m-%d')"}
|
||||
# # Create structured placeholder for distributed products
|
||||
# cat > helper-scripts/output/release-notes/release-notes-${{ github.event.inputs.product }}-${{ github.event.inputs.version }}.md << EOF
|
||||
# ## ${{ github.event.inputs.version }} {date="$(date +'%Y-%m-%d')"}
|
||||
|
||||
### Features
|
||||
# ### Features
|
||||
|
||||
- TODO: Add features for ${{ github.event.inputs.product }} ${{ github.event.inputs.version }}
|
||||
# - TODO: Add features for ${{ github.event.inputs.product }} ${{ github.event.inputs.version }}
|
||||
|
||||
### Bug Fixes
|
||||
# ### Bug Fixes
|
||||
|
||||
- TODO: Add bug fixes for ${{ github.event.inputs.product }} ${{ github.event.inputs.version }}
|
||||
# - TODO: Add bug fixes for ${{ github.event.inputs.product }} ${{ github.event.inputs.version }}
|
||||
|
||||
### Performance Improvements
|
||||
# ### Performance Improvements
|
||||
|
||||
- TODO: Add performance improvements for ${{ github.event.inputs.product }} ${{ github.event.inputs.version }}
|
||||
EOF
|
||||
# - TODO: Add performance improvements for ${{ github.event.inputs.product }} ${{ github.event.inputs.version }}
|
||||
# EOF
|
||||
|
||||
echo "generated=true" >> $GITHUB_OUTPUT
|
||||
# echo "generated=true" >> $GITHUB_OUTPUT
|
||||
|
||||
- name: Upload release notes
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: release-notes-${{ github.event.inputs.product }}-${{ github.event.inputs.version }}
|
||||
path: helper-scripts/output/release-notes/
|
||||
retention-days: 30
|
||||
# - name: Upload release notes
|
||||
# uses: actions/upload-artifact@v4
|
||||
# with:
|
||||
# name: release-notes-${{ github.event.inputs.product }}-${{ github.event.inputs.version }}
|
||||
# path: helper-scripts/output/release-notes/
|
||||
# retention-days: 30
|
||||
|
||||
audit-cli-documentation:
|
||||
name: Audit CLI Documentation
|
||||
|
|
@ -214,70 +211,70 @@ jobs:
|
|||
path: helper-scripts/output/cli-audit/
|
||||
retention-days: 90
|
||||
|
||||
audit-distributed-documentation:
|
||||
name: Audit Distributed Products Documentation
|
||||
needs: generate-release-notes-distributed
|
||||
runs-on: ubuntu-latest
|
||||
if: needs.generate-release-notes-distributed.outputs.generated == 'true' && contains(fromJSON('["clustered", "cloud-dedicated", "cloud-serverless"]'), github.event.inputs.product)
|
||||
# audit-distributed-documentation:
|
||||
# name: Audit Distributed Products Documentation
|
||||
# needs: generate-release-notes-distributed
|
||||
# runs-on: ubuntu-latest
|
||||
# if: needs.generate-release-notes-distributed.outputs.generated == 'true' && contains(fromJSON('["clustered", "cloud-dedicated", "cloud-serverless"]'), github.event.inputs.product)
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
# steps:
|
||||
# - uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '18'
|
||||
cache: 'yarn'
|
||||
# - name: Set up Node.js
|
||||
# uses: actions/setup-node@v4
|
||||
# with:
|
||||
# node-version: '18'
|
||||
# cache: 'yarn'
|
||||
|
||||
- name: Install dependencies
|
||||
run: yarn install --frozen-lockfile
|
||||
# - name: Install dependencies
|
||||
# run: yarn install --frozen-lockfile
|
||||
|
||||
- name: Run distributed products audit
|
||||
run: |
|
||||
PRODUCT="${{ github.event.inputs.product }}"
|
||||
VERSION="${{ github.event.inputs.version }}"
|
||||
# - name: Run distributed products audit
|
||||
# run: |
|
||||
# PRODUCT="${{ github.event.inputs.product }}"
|
||||
# VERSION="${{ github.event.inputs.version }}"
|
||||
|
||||
echo "Auditing distributed product: $PRODUCT v$VERSION"
|
||||
# TODO: Implement distributed products audit for release
|
||||
# This would audit API docs, deployment guides, configuration references
|
||||
# node ./helper-scripts/influxdb3-distributed/audit-documentation.js $PRODUCT $VERSION
|
||||
# echo "Auditing distributed product: $PRODUCT v$VERSION"
|
||||
# # TODO: Implement distributed products audit for release
|
||||
# # This would audit API docs, deployment guides, configuration references
|
||||
# # node ./helper-scripts/influxdb3-distributed/audit-documentation.js $PRODUCT $VERSION
|
||||
|
||||
# For now, create placeholder report
|
||||
mkdir -p helper-scripts/output/distributed-audit
|
||||
cat > helper-scripts/output/distributed-audit/release-audit-$PRODUCT-$VERSION.md << 'EOF'
|
||||
# Release Audit Report - Distributed Products
|
||||
# # For now, create placeholder report
|
||||
# mkdir -p helper-scripts/output/distributed-audit
|
||||
# cat > helper-scripts/output/distributed-audit/release-audit-$PRODUCT-$VERSION.md << 'EOF'
|
||||
# # Release Audit Report - Distributed Products
|
||||
|
||||
**Product:** $PRODUCT
|
||||
**Version:** $VERSION
|
||||
**Date:** $(date)
|
||||
**Status:** Placeholder - audit not yet implemented
|
||||
# **Product:** $PRODUCT
|
||||
# **Version:** $VERSION
|
||||
# **Date:** $(date)
|
||||
# **Status:** Placeholder - audit not yet implemented
|
||||
|
||||
## Areas to Audit
|
||||
- API documentation completeness
|
||||
- Deployment guide accuracy
|
||||
- Configuration reference updates
|
||||
- Integration guide updates
|
||||
- Version-specific feature documentation
|
||||
# ## Areas to Audit
|
||||
# - API documentation completeness
|
||||
# - Deployment guide accuracy
|
||||
# - Configuration reference updates
|
||||
# - Integration guide updates
|
||||
# - Version-specific feature documentation
|
||||
|
||||
## TODO
|
||||
- Implement API documentation audit
|
||||
- Implement deployment guide audit
|
||||
- Implement configuration reference audit
|
||||
- Implement integration guide audit
|
||||
EOF
|
||||
# ## TODO
|
||||
# - Implement API documentation audit
|
||||
# - Implement deployment guide audit
|
||||
# - Implement configuration reference audit
|
||||
# - Implement integration guide audit
|
||||
# EOF
|
||||
|
||||
- name: Upload distributed audit reports
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: distributed-audit-release-${{ github.event.inputs.product }}-${{ github.event.inputs.version }}
|
||||
path: helper-scripts/output/distributed-audit/
|
||||
retention-days: 90
|
||||
# - name: Upload distributed audit reports
|
||||
# uses: actions/upload-artifact@v4
|
||||
# with:
|
||||
# name: distributed-audit-release-${{ github.event.inputs.product }}-${{ github.event.inputs.version }}
|
||||
# path: helper-scripts/output/distributed-audit/
|
||||
# retention-days: 90
|
||||
|
||||
create-documentation-pr:
|
||||
name: Create Documentation PR
|
||||
needs: [generate-release-notes-core-enterprise, generate-release-notes-distributed, audit-cli-documentation, audit-distributed-documentation]
|
||||
needs: [generate-release-notes-core-enterprise, audit-cli-documentation]
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event.inputs.dry_run != 'true' && always() && (needs.generate-release-notes-core-enterprise.result == 'success' || needs.generate-release-notes-distributed.result == 'success')
|
||||
if: github.event.inputs.dry_run != 'true' && always() && (needs.generate-release-notes-core-enterprise.result == 'success')
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
|
@ -379,9 +376,9 @@ jobs:
|
|||
|
||||
create-audit-issue:
|
||||
name: Create Audit Issue
|
||||
needs: [audit-cli-documentation, audit-distributed-documentation]
|
||||
needs: [audit-cli-documentation]
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event.inputs.dry_run != 'true' && always() && (needs.audit-cli-documentation.result == 'success' || needs.audit-distributed-documentation.result == 'success')
|
||||
if: github.event.inputs.dry_run != 'true' && always() && (needs.audit-cli-documentation.result == 'success')
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
|
@ -476,7 +473,7 @@ jobs:
|
|||
|
||||
influxdb3-monolith-release-summary:
|
||||
name: Release Summary
|
||||
needs: [generate-release-notes-core-enterprise, generate-release-notes-distributed, audit-cli-documentation, audit-distributed-documentation, create-documentation-pr, create-audit-issue]
|
||||
needs: [generate-release-notes-core-enterprise, audit-cli-documentation, create-documentation-pr, create-audit-issue]
|
||||
runs-on: ubuntu-latest
|
||||
if: always()
|
||||
|
||||
|
|
@ -496,9 +493,7 @@ jobs:
|
|||
echo "| Step | Status |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Generate Release Notes (Core/Enterprise) | ${{ needs.generate-release-notes-core-enterprise.result }} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Generate Release Notes (Distributed) | ${{ needs.generate-release-notes-distributed.result }} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| CLI Documentation Audit | ${{ needs.audit-cli-documentation.result }} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Distributed Documentation Audit | ${{ needs.audit-distributed-documentation.result }} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Create Documentation PR | ${{ needs.create-documentation-pr.result }} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Create Audit Issue | ${{ needs.create-audit-issue.result }} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
|
|
|
|||
|
|
@ -72,12 +72,17 @@ jobs:
|
|||
Note: This is a placeholder file generated by the workflow.
|
||||
To generate actual release notes with commit history, run:
|
||||
|
||||
For Core/Enterprise:
|
||||
node ./helper-scripts/common/generate-release-notes.js \\
|
||||
--format core-enterprise \\
|
||||
--config ./helper-scripts/common/config/influxdb3-core-enterprise.json \\
|
||||
v$(echo "${{ inputs.version }}" | sed 's/^v//') \\
|
||||
v${{ inputs.version }} \\
|
||||
/path/to/influxdb \\
|
||||
/path/to/influxdb_pro
|
||||
v${{ inputs.version }}
|
||||
|
||||
For other products:
|
||||
node ./helper-scripts/common/generate-release-notes.js \\
|
||||
--config ./helper-scripts/common/config/[product-config].json \\
|
||||
v$(echo "${{ inputs.version }}" | sed 's/^v//') \\
|
||||
v${{ inputs.version }}
|
||||
-->
|
||||
EOF
|
||||
|
||||
|
|
|
|||
|
|
@ -32,17 +32,28 @@ helper-scripts/
|
|||
|
||||
## Common Scripts
|
||||
|
||||
### `common/generate-release-notes.sh`
|
||||
Generates release notes by analyzing git commits across multiple repositories.
|
||||
### `common/generate-release-notes.js`
|
||||
JavaScript ESM script that generates release notes by analyzing git commits across multiple repositories. Supports flexible configuration for different InfluxDB products and output formats.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./common/generate-release-notes.sh [--no-fetch] [--pull] <from_version> <to_version> <primary_repo_path> [additional_repo_paths...]
|
||||
node common/generate-release-notes.js [options] <from_version> <to_version> [repo_paths...]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
**Options:**
|
||||
- `--config <file>` - Load configuration from JSON file
|
||||
- `--format <type>` - Output format: 'integrated' or 'separated'
|
||||
- `--no-fetch` - Skip fetching latest commits from remote
|
||||
- `--pull` - Pull latest changes (use with caution)
|
||||
- `--no-pr-links` - Omit PR links from commit messages
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
./common/generate-release-notes.sh v3.1.0 v3.2.0 ~/repos/influxdb ~/repos/influxdb_iox
|
||||
# Using configuration file (recommended)
|
||||
node common/generate-release-notes.js --config common/config/influxdb3-core-enterprise.json v3.1.0 v3.2.0
|
||||
|
||||
# Traditional command-line arguments
|
||||
node common/generate-release-notes.js v3.1.0 v3.2.0 ~/repos/influxdb ~/repos/influxdb_pro
|
||||
```
|
||||
|
||||
### `common/update-product-version.sh`
|
||||
|
|
@ -92,7 +103,7 @@ output/
|
|||
These scripts are integrated with GitHub Actions workflows:
|
||||
|
||||
- **Workflow**: `.github/workflows/prepare-release.yml`
|
||||
- **Uses**: `generate-release-notes.sh`, `update-product-version.sh`
|
||||
- **Uses**: `generate-release-notes.js`, `update-product-version.sh`
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
|
@ -110,10 +121,10 @@ These scripts are integrated with GitHub Actions workflows:
|
|||
3. **Run a script**
|
||||
```bash
|
||||
# Generate release notes
|
||||
./common/generate-release-notes.sh v3.1.0 v3.2.0 ~/repos/influxdb
|
||||
node common/generate-release-notes.js --config common/config/influxdb3-core-enterprise.json v3.1.0 v3.2.0
|
||||
|
||||
# Audit CLI documentation
|
||||
./influxdb3-monolith/audit-cli-documentation.sh core local
|
||||
node influxdb3-monolith/audit-cli-documentation.js core local
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
|
|
|||
|
|
@ -4,31 +4,49 @@ This directory contains scripts that are shared across all InfluxDB documentatio
|
|||
|
||||
## Scripts
|
||||
|
||||
### generate-release-notes.sh
|
||||
### generate-release-notes.js
|
||||
|
||||
Generates release notes by analyzing git commits between two versions across multiple repositories.
|
||||
JavaScript ESM script that generates release notes by analyzing git commits between two versions across multiple repositories. Supports flexible configuration for different InfluxDB products and output formats.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./generate-release-notes.sh [options] <from_version> <to_version> <primary_repo> [additional_repos...]
|
||||
node generate-release-notes.js [options] <from_version> <to_version> [repo_paths...]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--config <file>` - Load configuration from JSON file (recommended)
|
||||
- `--format <type>` - Output format: 'integrated' or 'separated'
|
||||
- `--no-fetch` - Skip fetching latest commits from remote
|
||||
- `--pull` - Pull latest changes (use with caution)
|
||||
- `--no-pr-links` - Omit PR links from commit messages
|
||||
|
||||
**Example:**
|
||||
**Examples:**
|
||||
```bash
|
||||
# Generate release notes for v3.2.0
|
||||
./generate-release-notes.sh v3.1.0 v3.2.0 ~/repos/influxdb ~/repos/influxdb_iox
|
||||
# Using configuration file (recommended for InfluxDB 3 Core/Enterprise)
|
||||
node generate-release-notes.js --config config/influxdb3-core-enterprise.json v3.1.0 v3.2.0
|
||||
|
||||
# Using configuration file for other products
|
||||
node generate-release-notes.js --config config/influxdb3-clustered.json v1.0.0 v1.1.0
|
||||
|
||||
# Traditional command-line arguments
|
||||
node generate-release-notes.js v3.1.0 v3.2.0 ~/repos/influxdb ~/repos/influxdb_pro
|
||||
|
||||
# Skip fetch for faster local testing
|
||||
./generate-release-notes.sh --no-fetch v3.1.0 v3.2.0 ~/repos/influxdb
|
||||
node generate-release-notes.js --no-fetch v3.1.0 v3.2.0 ~/repos/influxdb
|
||||
```
|
||||
|
||||
**Configuration Files:**
|
||||
- `config/influxdb3-core-enterprise.json` - InfluxDB 3 Core/Enterprise separated format
|
||||
- `config/influxdb3-clustered.json` - InfluxDB 3 Clustered integrated format
|
||||
- `config/influxdb-v2.json` - InfluxDB v2.x integrated format
|
||||
|
||||
**Output:**
|
||||
- Creates `release-notes-<version>.md` in current directory
|
||||
- Creates `release-notes-<version>.md` in `../output/release-notes/`
|
||||
- Supports two formats:
|
||||
- **Integrated**: All repositories' changes combined in unified sections
|
||||
- **Separated**: Primary repository first, then secondary repositories (ideal for Core/Enterprise)
|
||||
- Includes sections for Features, Bug Fixes, Breaking Changes, Performance, and API changes
|
||||
- Automatically links to GitHub pull requests (configurable per repository)
|
||||
|
||||
### update-product-version.sh
|
||||
|
||||
|
|
|
|||
|
|
@ -9,9 +9,9 @@ These scripts help with documentation workflows for InfluxDB 3 Core and Enterpri
|
|||
## Prerequisites
|
||||
|
||||
- **Docker and Docker Compose**: For running InfluxDB 3 containers
|
||||
- **Node.js 16+**: For running JavaScript ESM scripts
|
||||
- **Active containers**: InfluxDB 3 Core and/or Enterprise containers running via `docker compose`
|
||||
- **Secret files**: Docker Compose secrets for auth tokens (`~/.env.influxdb3-core-admin-token` and `~/.env.influxdb3-enterprise-admin-token`)
|
||||
- **Python 3**: For API analysis scripts
|
||||
|
||||
## Scripts
|
||||
|
||||
|
|
@ -41,103 +41,74 @@ Creates and configures authentication tokens for InfluxDB 3 containers.
|
|||
./setup-auth-tokens.sh enterprise
|
||||
```
|
||||
|
||||
### 🔍 CLI Analysis
|
||||
### 🔍 CLI Documentation Audit
|
||||
|
||||
#### `detect-cli-changes.sh`
|
||||
Compares CLI help output between different InfluxDB 3 versions to identify changes.
|
||||
#### `audit-cli-documentation.js`
|
||||
JavaScript ESM script that audits InfluxDB 3 CLI commands against existing documentation to identify missing or outdated content.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./detect-cli-changes.sh [core|enterprise] <old-version> <new-version>
|
||||
node audit-cli-documentation.js [core|enterprise|both] [version|local]
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Compare any two versions (released or local containers)
|
||||
- Extract comprehensive help for all commands and subcommands
|
||||
- Generate unified diff reports
|
||||
- Create markdown summaries of changes
|
||||
- Handle authentication automatically
|
||||
- **NEW**: Analyze source code changes and correlate with CLI changes
|
||||
- **NEW**: Identify related features between CLI and backend modifications
|
||||
- **NEW**: Generate recommended documentation focus areas
|
||||
- Compares actual CLI help output with documented commands
|
||||
- Identifies missing documentation for new CLI options
|
||||
- Finds documented options that no longer exist in the CLI
|
||||
- Supports both released versions and local containers
|
||||
- Generates detailed audit reports with recommendations
|
||||
- Handles authentication automatically using Docker secrets
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Compare two released versions
|
||||
./detect-cli-changes.sh core 3.1.0 3.2.0
|
||||
# Audit Core documentation against local container
|
||||
node audit-cli-documentation.js core local
|
||||
|
||||
# Compare released vs local development container
|
||||
./detect-cli-changes.sh enterprise 3.1.0 local
|
||||
# Audit Enterprise documentation against specific version
|
||||
node audit-cli-documentation.js enterprise v3.2.0
|
||||
|
||||
# Use "local" to reference running Docker containers
|
||||
./detect-cli-changes.sh core 3.1.0 local
|
||||
# Audit both products against local containers
|
||||
node audit-cli-documentation.js both local
|
||||
```
|
||||
|
||||
**Output:**
|
||||
- `helper-scripts/output/cli-changes/cli-{product}-{version}.txt` - Full CLI help
|
||||
- `helper-scripts/output/cli-changes/cli-changes-{product}-{old}-to-{new}.diff` - Diff report
|
||||
- `helper-scripts/output/cli-changes/cli-changes-{product}-{old}-to-{new}-summary.md` - Enhanced summary with:
|
||||
- CLI changes analysis
|
||||
- Source code features, breaking changes, and API modifications
|
||||
- Cross-referenced CLI and source correlations
|
||||
- Recommended documentation focus areas
|
||||
- `helper-scripts/output/cli-changes/source-changes-{product}-{old}-to-{new}.md` - Full source code analysis (when available)
|
||||
- `../output/cli-audit/documentation-audit-{product}-{version}.md` - Detailed audit report
|
||||
- `../output/cli-audit/parsed-cli-{product}-{version}.md` - Parsed CLI structure
|
||||
- `../output/cli-audit/patches/{product}/` - Generated patches for missing documentation
|
||||
|
||||
#### `compare-cli-local.sh`
|
||||
Convenience script for comparing a released version against your local running container.
|
||||
### 🛠️ CLI Documentation Updates
|
||||
|
||||
#### `apply-cli-patches.js`
|
||||
JavaScript ESM script that applies generated patches to update CLI documentation with missing options.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./compare-cli-local.sh [core|enterprise] [released-version]
|
||||
node apply-cli-patches.js [core|enterprise|both] [--dry-run]
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Auto-starts containers if not running
|
||||
- Shows local container version
|
||||
- Provides quick testing commands
|
||||
- Streamlined workflow for development
|
||||
- Applies patches generated by `audit-cli-documentation.js`
|
||||
- Updates CLI reference documentation with missing options
|
||||
- Supports dry-run mode to preview changes
|
||||
- Maintains existing documentation structure and formatting
|
||||
- Creates backups before applying changes
|
||||
|
||||
**Example:**
|
||||
**Examples:**
|
||||
```bash
|
||||
# Compare Core local container vs 3.1.0 release
|
||||
./compare-cli-local.sh core 3.1.0
|
||||
# Preview changes without applying (dry run)
|
||||
node apply-cli-patches.js core --dry-run
|
||||
|
||||
# Apply patches to Enterprise documentation
|
||||
node apply-cli-patches.js enterprise
|
||||
|
||||
# Apply patches to both products
|
||||
node apply-cli-patches.js both
|
||||
```
|
||||
|
||||
### 🔧 Development Tools
|
||||
|
||||
#### `extract_influxdb3_help.py`
|
||||
Python script for extracting and parsing InfluxDB 3 CLI help output.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python3 extract_influxdb3_help.py [options]
|
||||
```
|
||||
|
||||
#### `compare_cli_api.py`
|
||||
Python script for comparing CLI commands with API endpoints to identify discrepancies.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python3 compare_cli_api.py [options]
|
||||
```
|
||||
|
||||
#### `update-product-version.sh`
|
||||
Updates product version numbers in `data/products.yml` and related files.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./update-product-version.sh --product [core|enterprise] --version X.Y.Z
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Updates `data/products.yml` with new version
|
||||
- Updates Docker Compose examples
|
||||
- Validates version format
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
./update-product-version.sh --product core --version 3.2.1
|
||||
```
|
||||
**Output:**
|
||||
- Updates CLI reference documentation files in place
|
||||
- Creates backup files with `.backup` extension
|
||||
- Logs all changes made to the documentation
|
||||
|
||||
## Quick Start Guide
|
||||
|
||||
|
|
@ -157,51 +128,52 @@ chmod +x *.sh
|
|||
docker compose down && docker compose up -d influxdb3-core influxdb3-enterprise
|
||||
```
|
||||
|
||||
### 2. Basic CLI Analysis
|
||||
### 2. CLI Documentation Audit
|
||||
|
||||
```bash
|
||||
# Start your containers
|
||||
docker compose up -d influxdb3-core influxdb3-enterprise
|
||||
|
||||
# Compare CLI between versions
|
||||
./detect-cli-changes.sh core 3.1.0 local
|
||||
./detect-cli-changes.sh enterprise 3.1.0 local
|
||||
# Audit CLI documentation
|
||||
node audit-cli-documentation.js core local
|
||||
node audit-cli-documentation.js enterprise local
|
||||
|
||||
# Review the output
|
||||
ls ../output/cli-changes/
|
||||
ls ../output/cli-audit/
|
||||
```
|
||||
|
||||
### 3. Development Workflow
|
||||
|
||||
```bash
|
||||
# Quick comparison during development
|
||||
./compare-cli-local.sh core 3.1.0
|
||||
# Audit documentation for both products
|
||||
node audit-cli-documentation.js both local
|
||||
|
||||
# Check what's changed
|
||||
cat ../output/cli-changes/cli-changes-core-3.1.0-to-local-summary.md
|
||||
# Check the audit results
|
||||
cat ../output/cli-audit/documentation-audit-core-local.md
|
||||
cat ../output/cli-audit/documentation-audit-enterprise-local.md
|
||||
|
||||
# Apply patches if needed (dry run first)
|
||||
node apply-cli-patches.js both --dry-run
|
||||
```
|
||||
|
||||
### 4. Enhanced Analysis with Source Code Correlation
|
||||
### 4. Release Documentation Updates
|
||||
|
||||
When comparing two released versions (not using "local"), the script automatically:
|
||||
For release documentation, use the audit and patch workflow:
|
||||
|
||||
```bash
|
||||
# Run CLI comparison with source analysis
|
||||
./detect-cli-changes.sh enterprise 3.1.0 3.2.0
|
||||
# Audit against released version
|
||||
node audit-cli-documentation.js enterprise v3.2.0
|
||||
|
||||
# Review the enhanced summary that includes:
|
||||
# - CLI changes
|
||||
# - Source code changes (features, fixes, breaking changes)
|
||||
# - Correlation between CLI and backend
|
||||
# - Recommended documentation focus areas
|
||||
cat ../output/cli-changes/cli-changes-enterprise-3.1.0-to-3.2.0-summary.md
|
||||
# Review missing documentation
|
||||
cat ../output/cli-audit/documentation-audit-enterprise-v3.2.0.md
|
||||
|
||||
# Apply patches to update documentation
|
||||
node apply-cli-patches.js enterprise
|
||||
|
||||
# Verify changes look correct
|
||||
git diff content/influxdb3/enterprise/reference/cli/
|
||||
```
|
||||
|
||||
**Requirements for source analysis:**
|
||||
- InfluxDB source repository available (searches common locations)
|
||||
- Git tags for the versions being compared (e.g., v3.1.0, v3.2.0)
|
||||
- Works best with the `generate-release-notes.sh` script in parent directory
|
||||
|
||||
## Container Integration
|
||||
|
||||
The scripts work with your Docker Compose setup:
|
||||
|
|
@ -219,59 +191,59 @@ The scripts work with your Docker Compose setup:
|
|||
|
||||
### 📋 Release Documentation
|
||||
|
||||
1. **Pre-release analysis:**
|
||||
1. **Pre-release audit:**
|
||||
```bash
|
||||
./detect-cli-changes.sh core 3.1.0 3.2.0
|
||||
node audit-cli-documentation.js core v3.2.0
|
||||
```
|
||||
|
||||
2. **Update documentation based on changes**
|
||||
3. **Test new commands and options**
|
||||
4. **Update CLI reference pages**
|
||||
2. **Review audit results and update documentation**
|
||||
3. **Apply patches for missing content**
|
||||
4. **Test documented commands work correctly**
|
||||
|
||||
### 🔬 Development Testing
|
||||
|
||||
1. **Compare local development:**
|
||||
1. **Audit local development:**
|
||||
```bash
|
||||
./compare-cli-local.sh enterprise 3.1.0
|
||||
node audit-cli-documentation.js enterprise local
|
||||
```
|
||||
|
||||
2. **Verify new features work**
|
||||
2. **Verify new features are documented**
|
||||
3. **Test authentication setup**
|
||||
4. **Validate CLI consistency**
|
||||
4. **Apply patches to keep docs current**
|
||||
|
||||
### 🚀 Release Preparation
|
||||
|
||||
1. **Update version numbers:**
|
||||
1. **Final audit before release:**
|
||||
```bash
|
||||
./update-product-version.sh --product core --version 3.2.1
|
||||
node audit-cli-documentation.js both local
|
||||
```
|
||||
|
||||
2. **Generate change reports**
|
||||
2. **Apply all pending patches**
|
||||
3. **Update examples and tutorials**
|
||||
4. **Verify all CLI commands work as documented**
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
helper-scripts/
|
||||
├── output/
|
||||
│ └── cli-changes/
|
||||
│ ├── cli-core-3.1.0.txt # Full CLI help
|
||||
│ ├── cli-core-3.2.0.txt # Full CLI help
|
||||
│ ├── cli-changes-core-3.1.0-to-3.2.0.diff # Diff report
|
||||
│ ├── cli-changes-core-3.1.0-to-3.2.0-summary.md # Enhanced summary with:
|
||||
│ │ # - CLI changes
|
||||
│ │ # - Source code analysis
|
||||
│ │ # - CLI/Source correlations
|
||||
│ │ # - Documentation recommendations
|
||||
│ └── source-changes-core-3.1.0-to-3.2.0.md # Full source analysis
|
||||
│ └── cli-audit/
|
||||
│ ├── documentation-audit-core-local.md # CLI documentation audit report
|
||||
│ ├── documentation-audit-enterprise-v3.2.0.md # CLI documentation audit report
|
||||
│ ├── parsed-cli-core-local.md # Parsed CLI structure
|
||||
│ ├── parsed-cli-enterprise-v3.2.0.md # Parsed CLI structure
|
||||
│ └── patches/
|
||||
│ ├── core/ # Generated patches for Core
|
||||
│ │ ├── influxdb3-cli-patch-001.md
|
||||
│ │ └── influxdb3-cli-patch-002.md
|
||||
│ └── enterprise/ # Generated patches for Enterprise
|
||||
│ ├── influxdb3-cli-patch-001.md
|
||||
│ └── influxdb3-cli-patch-002.md
|
||||
└── influxdb3-monolith/
|
||||
├── README.md # This file
|
||||
├── setup-auth-tokens.sh # Auth setup
|
||||
├── detect-cli-changes.sh # CLI comparison with source analysis
|
||||
├── compare-cli-local.sh # Local comparison
|
||||
├── extract_influxdb3_help.py # Help extraction
|
||||
├── compare_cli_api.py # CLI/API comparison
|
||||
└── update-product-version.sh # Version updates
|
||||
├── audit-cli-documentation.js # CLI documentation audit
|
||||
└── apply-cli-patches.js # CLI documentation patches
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
|
@ -307,9 +279,7 @@ docker pull influxdb:3-enterprise:3.2.0
|
|||
|
||||
Enable debug output for troubleshooting:
|
||||
```bash
|
||||
set -x
|
||||
./detect-cli-changes.sh core 3.1.0 local
|
||||
set +x
|
||||
DEBUG=1 node audit-cli-documentation.js core local
|
||||
```
|
||||
|
||||
## Integration with CI/CD
|
||||
|
|
@ -317,29 +287,29 @@ set +x
|
|||
### GitHub Actions Example
|
||||
|
||||
```yaml
|
||||
- name: Detect CLI Changes
|
||||
- name: Audit CLI Documentation
|
||||
run: |
|
||||
cd helper-scripts/influxdb3-monolith
|
||||
./detect-cli-changes.sh core ${{ env.OLD_VERSION }} ${{ env.NEW_VERSION }}
|
||||
node audit-cli-documentation.js core ${{ env.VERSION }}
|
||||
|
||||
- name: Upload CLI Analysis
|
||||
- name: Upload CLI Audit Results
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: cli-analysis
|
||||
path: helper-scripts/output/cli-changes/
|
||||
name: cli-audit
|
||||
path: helper-scripts/output/cli-audit/
|
||||
```
|
||||
|
||||
### CircleCI Example
|
||||
|
||||
```yaml
|
||||
- run:
|
||||
name: CLI Change Detection
|
||||
name: CLI Documentation Audit
|
||||
command: |
|
||||
cd helper-scripts/influxdb3-monolith
|
||||
./detect-cli-changes.sh enterprise 3.1.0 3.2.0
|
||||
node audit-cli-documentation.js enterprise v3.2.0
|
||||
|
||||
- store_artifacts:
|
||||
path: helper-scripts/output/cli-changes/
|
||||
path: helper-scripts/output/cli-audit/
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
|
@ -350,15 +320,15 @@ set +x
|
|||
- Use minimal token permissions when possible
|
||||
|
||||
### 📚 Documentation
|
||||
- Run comparisons early in release cycle
|
||||
- Review all diff output for breaking changes
|
||||
- Update examples to use new features
|
||||
- Test all documented commands
|
||||
- Run audits early in release cycle
|
||||
- Review all audit reports for missing content
|
||||
- Apply patches to keep documentation current
|
||||
- Test all documented commands work correctly
|
||||
|
||||
### 🔄 Workflow
|
||||
- Use `local` version for development testing
|
||||
- Compare against previous stable release
|
||||
- Generate reports before documentation updates
|
||||
- Audit against released versions for release prep
|
||||
- Generate patches before documentation updates
|
||||
- Validate changes with stakeholders
|
||||
|
||||
## Troubleshooting
|
||||
|
|
@ -370,8 +340,8 @@ chmod +x *.sh
|
|||
|
||||
### Missing Dependencies
|
||||
```bash
|
||||
# Python dependencies
|
||||
pip3 install -r requirements.txt # if exists
|
||||
# Node.js dependencies
|
||||
node --version # Should be 16 or higher
|
||||
|
||||
# Docker Compose
|
||||
docker compose version
|
||||
|
|
@ -401,5 +371,3 @@ When adding new scripts to this directory:
|
|||
|
||||
- [InfluxDB 3 Core CLI Reference](/influxdb3/core/reference/cli/)
|
||||
- [InfluxDB 3 Enterprise CLI Reference](/influxdb3/enterprise/reference/cli/)
|
||||
- [Release Process Documentation](../../.context/templates/release-checklist-template.md)
|
||||
- [CLI Testing Guide](../../.context/templates/cli-testing-guide.md)
|
||||
Loading…
Reference in New Issue