diff --git a/RELEASE_VISIBILITY_ENHANCEMENT.md b/RELEASE_VISIBILITY_ENHANCEMENT.md new file mode 100644 index 000000000..124435a2e --- /dev/null +++ b/RELEASE_VISIBILITY_ENHANCEMENT.md @@ -0,0 +1,213 @@ +# Release Visibility Enhancement - Implementation Plan + +## Issue Description +Reference: https://all.devstats.cncf.io/d/53/projects-health-table?orgId=1 + +Currently, release information is displayed at the bottom of the Projects Health Table dashboard. This enhancement will: +1. Move release information to the top of the table for better visibility +2. Parse release versions to distinguish between major, minor, and patch releases (following semantic versioning major.minor.patch) +3. Help identify projects in "maintenance mode" (where minor versions haven't changed in years) + +## Benefits +- **Enhanced Visibility**: Release information immediately visible without scrolling +- **Maintenance Mode Detection**: Quickly identify projects with stagnant minor versions +- **Better User Experience**: Improved dashboard usability for project health assessment +- **Governance Insights**: Help CNCF understand project maturity and activity levels + +## Current Implementation Analysis + +### Files Affected +1. **SQL Metrics**: `metrics/shared/projects_health.sql` (2189 lines) + - Generates health metrics for all CNCF projects + - Currently includes: `last_release_date`, `last_release_tag`, `last_release_desc` + - Release metrics appear at bottom (lines 1012-1027) + +2. **HTML Template**: `partials/projects_health.html` (855 lines) + - Generates the visual table with all projects + - Uses loop structures to dynamically populate data + - Currently renders release info at the end of the table + +3. **Grafana Dashboard**: `grafana/dashboards/all/projects-health-table.json` + - References the HTML partial for rendering + - May need update to refresh correctly + +### Current Release Metrics (Bottom of Table) +```sql +-- Line 1012-1027 in projects_health.sql +'Releases: Last release' -- Line 1013 +'Releases: Last release date' -- Line 1021 +``` + +Current fields: +- `last_release_date`: Date of most recent release +- `last_release_tag`: Version tag (e.g., "v1.28.0", "2.0.5") +- `last_release_desc`: Release description + +## Proposed Solution + +### Phase 1: Version Parsing Enhancement +Add semantic version parsing to SQL query to extract: +- **Major version**: First number (e.g., "1" from "v1.28.0") +- **Minor version**: Second number (e.g., "28" from "v1.28.0") +- **Patch version**: Third number (e.g., "0" from "v1.28.0") + +#### SQL Enhancement Strategy +```sql +-- New computed columns to add: +release_major: Extract major version number +release_minor: Extract minor version number +release_patch: Extract patch version number +release_sem_ver: Formatted as "major.minor.patch" +maintenance_mode: Boolean flag (true if minor version unchanged > 2 years) +``` + +#### Version Parsing Logic +```sql +-- Handle various version formats: +-- v1.28.0, 1.28.0, v1.28, 1.28, etc. +-- Use regex or string functions: +regexp_replace(last_release_tag, '^v?([0-9]+)\.([0-9]+)\.?([0-9]+)?.*$', '\1') as release_major +regexp_replace(last_release_tag, '^v?([0-9]+)\.([0-9]+)\.?([0-9]+)?.*$', '\2') as release_minor +regexp_replace(last_release_tag, '^v?([0-9]+)\.([0-9]+)\.?([0-9]+)?.*$', '\3') as release_patch +``` + +### Phase 2: HTML Template Reorganization +Move release information rows from bottom to top of table: + +**New Row Order** (after project names): +1. Project names (current row 2) +2. **NEW: Release version (major.minor.patch)** +3. **NEW: Last release date** +4. **NEW: Maintenance mode indicator** +5. Activity status (current row 3) +6. ... rest of existing metrics ... + +#### Visual Enhancements +- **Color coding for maintenance mode**: + - 🟢 Green: Active development (minor version changed < 1 year) + - 🟡 Yellow: Slow updates (minor version unchanged 1-2 years) + - 🔴 Red: Maintenance mode (minor version unchanged > 2 years) + +- **Version display format**: + - Current: "v1.28.0" + - Enhanced: "1.28.0" with tooltip showing full tag + +### Phase 3: Maintenance Mode Detection Logic +```sql +-- Flag projects where minor version hasn't changed +WITH version_history AS ( + SELECT + period as project, + regexp_replace(title, '^v?([0-9]+)\.([0-9]+)\.?([0-9]+)?.*$', '\1.\2') as major_minor, + time as release_date + FROM sannotations_shared + WHERE title != 'CNCF join date' +), +latest_minor_change AS ( + SELECT + project, + MAX(release_date) as last_minor_change + FROM version_history + GROUP BY project, major_minor +) +-- Calculate days since last minor version change +``` + +## Implementation Steps + +### Step 1: Update SQL Query (projects_health.sql) +1. Add version parsing logic to extract major, minor, patch +2. Add maintenance mode detection +3. Move release-related SELECT statements to top of union queries (after activity status) +4. Test query performance with new regex operations + +### Step 2: Update HTML Template (projects_health.html) +1. Locate release information rows (search for "Releases: Last release") +2. Cut those row sections +3. Paste them after project name row and activity status row +4. Update loop indices if needed +5. Add CSS styling for maintenance mode colors +6. Add tooltips for version information + +### Step 3: CSS Styling +Add new styles to `