feature-gates-gap

name	feature-gates-gap
description	Analyze OpenShift feature gate differences between versions. Identifies new feature gates, removed gates, and default enablement changes. Logs detected feature gate changes but always exits 0 on successful execution. Automatically generates comprehensive reports in HTML and JSON formats.
compatibility	{"required_tools":["python3","curl (for Sippy API access)","jq (for JSON processing)"]}

Feature Gate Gap Analysis

Analyze differences in OpenShift feature gates between versions using the Sippy API.

When to Use

• Comparing feature gates between versions
• Planning cluster upgrades
• Understanding new capabilities in a release
• Tracking feature graduation (TechPreview → Default)
• CI/CD pipelines that need to detect feature changes

Workflow

1. Parse baseline and target versions (default: auto-detect latest stable → latest candidate)
2. Fetch feature gate data from Sippy API for both versions
3. Compare Hypershift-relevant feature gates only (gates with Default:Hypershift, DevPreviewNoUpgrade:Hypershift, or TechPreviewNoUpgrade:Hypershift enablement) and identify:
   • New feature gates added in target version
   • Feature gates removed in target version
   • Feature gates newly enabled by default (Default:Hypershift) in target
   • Feature gates removed from default in target
   • Feature gates that continue as Default:Hypershift (already default, still default)
4. Log detected differences and always exit 0 on successful execution

Script Usage

Single version (recommended):

# Auto-resolves baseline and target
python3 ./scripts/gap-feature-gates.py --version 4.22

# Using environment variable
OPENSHIFT_VERSION=4.22 python3 ./scripts/gap-feature-gates.py

# 5.x versions (special baseline mapping)
python3 ./scripts/gap-feature-gates.py --version 5.0   # 4.22 → 5.0
OPENSHIFT_VERSION=5.1 python3 ./scripts/gap-feature-gates.py  # 4.23 → 5.1

# With verbose output
python3 ./scripts/gap-feature-gates.py --version 4.22 --verbose

# Custom report directory
python3 ./scripts/gap-feature-gates.py --version 4.22 --report-dir /custom/reports

Explicit baseline and target:

python3 ./scripts/gap-feature-gates.py \
  --baseline <version> \
  --target <version> \
  [--report-dir <path>] \
  [--verbose]

# Examples
python3 ./scripts/gap-feature-gates.py --baseline 4.21 --target 4.22
python3 ./scripts/gap-feature-gates.py --baseline 4.21 --target 4.22 --verbose

Auto-detect (no arguments):

# Compares latest stable → latest candidate
python3 ./scripts/gap-feature-gates.py

# Use nightly as target
TARGET_VERSION=NIGHTLY python3 ./scripts/gap-feature-gates.py

# Custom report location
REPORT_DIR=/ci-artifacts python3 ./scripts/gap-feature-gates.py

Generated Reports:

reports/gap-analysis-feature-gates_4.21_to_4.22_20260325_120000.html  # HTML
reports/gap-analysis-feature-gates_4.21_to_4.22_20260325_120000.json  # JSON

Exit Codes:

• 0: Successful execution (regardless of whether differences were found)
• 1: Execution failure (e.g., missing tools, network errors, invalid versions)

Version Resolution:

• --version flag > OPENSHIFT_VERSION env var > --baseline AND --target (both required) > BASE_VERSION AND TARGET_VERSION (both required) > Auto-detect
• Auto-detect: latest stable (baseline) → latest candidate (target)
• Special keywords: TARGET_VERSION=NIGHTLY or TARGET_VERSION=CANDIDATE

Key Focus Areas

Note: Only Hypershift-relevant gates are analyzed (gates with Default:Hypershift, DevPreviewNoUpgrade:Hypershift, or TechPreviewNoUpgrade:Hypershift enablement).

• New Feature Gates: Hypershift-relevant gates added in the target version
• Removed Feature Gates: Hypershift-relevant gates dropped from the target version
• Default Enablement: Gates newly enabled by default (Default:Hypershift) - important for upgrade planning
• Removed from Default: Gates that had Default:Hypershift in baseline but no longer do
• Continues as Default: Gates that continue as Default:Hypershift from baseline to target

Output

The script outputs log messages and always exits 0 on successful execution:

No differences:

[INFO] Starting Feature Gate Gap Analysis
[INFO] Baseline version: 4.21
[INFO] Target version: 4.22
[INFO] Fetching feature gates for version 4.21...
[SUCCESS] Fetched 125 feature gates for version 4.21
[INFO] Fetching feature gates for version 4.22...
[SUCCESS] Fetched 125 feature gates for version 4.22
[INFO] Comparing feature gates...
[SUCCESS] No feature gate differences found between 4.21 and 4.22

Exit code: 0 (successful execution, no differences)

Differences found:

[INFO] Starting Feature Gate Gap Analysis
[INFO] Baseline version: 4.21
[INFO] Target version: 4.22
[INFO] Fetching feature gates for version 4.21...
[SUCCESS] Fetched 125 feature gates for version 4.21
[INFO] Fetching feature gates for version 4.22...
[SUCCESS] Fetched 130 feature gates for version 4.22
[INFO] Comparing feature gates...
[INFO] Feature gate differences detected (Hypershift-relevant only):
[INFO]   - New feature gates: 8
[INFO]   - Removed feature gates: 3
[INFO]   - Newly enabled by default (Default:Hypershift): 2
[INFO]   - Continues as Default:Hypershift: 5

Exit code: 0 (successful execution, differences found)

With --verbose:

[INFO] Feature gate differences detected:
[INFO]   - New feature gates: 8
[INFO]   - Newly enabled by default: 2

[INFO] New feature gates in 4.22:
[INFO]   + NewFeatureGate1
[INFO]   + NewFeatureGate2
[INFO]   + NewFeatureGate3
[INFO]   + NewFeatureGate4
[INFO]   + NewFeatureGate5
[INFO]   + NewFeatureGate6
[INFO]   + NewFeatureGate7
[INFO]   + NewFeatureGate8

[INFO] Newly enabled by default in 4.22:
[INFO]   ✓ PreviouslyTechPreviewGate
[INFO]   ✓ AnotherGraduatedGate

Use in CI/CD:

# Script always exits 0 on success
python3 ./scripts/gap-feature-gates.py --baseline 4.21 --target 4.22

# Check for differences by parsing output
if python3 ./scripts/gap-feature-gates.py --baseline 4.21 --target 4.22 2>&1 | grep -q "Feature gate differences detected"; then
  echo "Feature gate changes detected - review reports/"
else
  echo "No feature gate changes"
fi

# Use JSON report for programmatic analysis
python3 ./scripts/gap-feature-gates.py --baseline 4.21 --target 4.22
if jq -e '.comparison.added | length > 0' reports/gap-analysis-feature-gates_*.json >/dev/null 2>&1; then
  echo "New feature gates detected"
fi

Data Source

Uses Sippy API to fetch feature gate information:

• API endpoint: https://sippy.dptools.openshift.org/api/feature_gates?release=<version>
• Data includes:
  • Feature gate names
  • Enablement status (Default, DevPreviewNoUpgrade, TechPreviewNoUpgrade)
  • Platform variations (Hypershift, SelfManagedHA)
  • First seen version

Going Beyond the Script

Detailed Analysis:

# Get raw feature gate data for manual analysis
curl -s "https://sippy.dptools.openshift.org/api/feature_gates?release=4.22" | jq '.'

# Filter for default-enabled gates only
curl -s "https://sippy.dptools.openshift.org/api/feature_gates?release=4.22" | \
  jq '.[] | select(.enabled[] | contains("Default:"))'

# Count gates by enablement level
curl -s "https://sippy.dptools.openshift.org/api/feature_gates?release=4.22" | \
  jq '[.[] | .enabled[] | split(":")[0]] | group_by(.) | map({key: .[0], count: length})'

Understanding Feature Gate Lifecycle:

• TechPreviewNoUpgrade: Early preview, no upgrade support
• DevPreviewNoUpgrade: Developer preview, no upgrade support
• Default: Enabled by default, production ready

CI/CD Integration:

• Parse script output to detect feature gate changes
• Script always exits 0 on successful execution regardless of differences
• Automate notifications when feature gates change
• Track feature graduation across releases

Impact Analysis:

• New default-enabled gates may affect cluster behavior
• Removed gates indicate deprecated features
• Gates graduating to default indicate feature stabilization

Z-Stream Comparison

When comparing z-stream versions (same minor version, e.g., 4.21.15 → 4.21.16):

[INFO] Starting Feature Gate Gap Analysis
[INFO] Baseline version: 4.21.15 (minor: 4.21)
[INFO] Target version: 4.21.16 (minor: 4.21)
[INFO] Comparison type: Z-stream (same minor version)
[INFO] Z-stream comparison detected: 4.21.15 → 4.21.16
[INFO] Z-stream updates should not introduce/remove feature gates
[INFO] Showing default feature gates for 4.21
[SUCCESS] Found 23 Default:Hypershift gates in 4.21
[INFO] Total Hypershift-relevant gates: 45

Behavior:

• Z-stream updates (e.g., 4.21.15 → 4.21.16) should not change feature gates
• Report shows default feature gates for the version instead of differences
• Exit code still 0 (informational only)

HTML Report UI:

• Default gates table is wrapped in a collapsible drop-down
• Summary shows: "📋 View all N Default:Hypershift gates (click to expand)"
• Click to expand/collapse the full list of default gates
• Helps keep reports concise while providing full details on demand

Cross-minor comparison (e.g., 4.21 → 4.22) shows differences as usual.