feat: implement semantic versioning and fix upstream sync + Slack notifications #35

mateo-di · 2025-11-20T18:05:28Z

Description

This PR implements comprehensive improvements to CARTO's LiteLLM fork versioning, notification system, and upstream sync reliability.

Summary of Changes

1. CARTO Semantic Versioning Strategy

New version format: v{upstream}-carto.{MAJOR}.{MINOR}.{PATCH}
Example: v1.79.1-carto.1.7.1 (upstream v1.79.1, CARTO version 1.7.1)
CARTO version accumulates (never resets) and tracks customizations independently
Calculated automatically from conventional commits

2. Version Calculation Script

New file: .github/scripts/calculate_carto_version.sh
Analyzes commits since last release using conventional commit patterns
Filters by CARTO authors (@carto.com, @cartodb.com)
Excludes upstream sync/merge commits
Applies semantic versioning rules chronologically

3. Release Workflow Improvements

Removed broken semver-generator dependency
Integrated custom version calculation script
Enhanced Claude prompt with upstream sync context
Upstream version change detection
Added Slack notifications to cartodb-ops channel after releases

4. Sync Workflow Slack Fixes

Added comprehensive error handling with retry logic (3 attempts)
Slack API response validation
Secret existence checks
Detailed logging and GitHub Actions annotations

5. Upstream Commit History Preservation (New)

Problem: GitHub showed ~3000 commits behind despite successful syncs
Root Cause: git reset --hard in workflow broke commit history lineage
Solution:
- Removed git reset --hard fallback completely
- Enhanced conflict resolution within merge (preserves upstream commit SHAs)
- Removed force-push requirement
- Next sync will automatically repair history
Impact: GitHub will show accurate "commits behind" count after next sync
Commit: 15076adb - fix: preserve upstream commit history in sync workflow

6. Slack Notification Enhancements

Updated channel to C09K0M5MP7V (cartodb-ops)
Added LiteLLM context for recipients
Structured format with action-required labels
Better formatting for readability

7. Documentation

Comprehensive versioning strategy in CARTO_CLAUDE.md
Conventional commits guidelines and examples
Team guidance on commit format requirements
Detailed commit history preservation explanation (project docs)

Type of change

Feature
Fix
Documentation

Acceptance

Version Calculation
- Run .github/scripts/calculate_carto_version.sh "" "1.79.1" to verify initial version calculation
- Should output: v1.79.1-carto.1.7.1
Release Workflow
- Trigger next CARTO release workflow
- Verify new version tag is calculated correctly
- Check release notes separate CARTO vs upstream changes
- Verify Slack notification sent to cartodb-ops channel
Sync Workflow
- Wait for next weekly upstream sync
- Verify Slack notification for new sync PR
- Check error handling if Slack fails
Commit History Preservation
- After next sync, check GitHub UI: https://github.com/CartoDB/litellm
- Verify "commits behind" count is accurate (0 or small number)
- Run: git rev-list --count origin/main..upstream/main (should be 0 or very small)
Documentation
- Review CARTO_CLAUDE.md versioning section
- Confirm commit format guidelines are clear

Context

Motivation:

Previous versioning counted ALL repo commits (1,740+), resulting in incorrect version 1.74.336
Slack notifications were silently failing with no error messages
Release notes didn't distinguish CARTO customizations from upstream changes
Need sustainable strategy for weekly upstream syncs + manual CARTO releases
GitHub showed 3000+ commits behind despite successful syncs (history broken by reset)

Design Decisions:

Hybrid format shows both upstream base and CARTO customizations
Only count commits from CARTO team members
Conventional commits enable automatic version calculation
Calculated initial version from historical commits: v1.79.1-carto.1.7.1 (7 features, 9 fixes)
Use merge (not reset) to preserve upstream commit history and lineage

Basic checklist

Good PR name
Just one issue per PR (versioning + notifications + sync reliability)
GitHub labels (will add after PR creation)
Proper status & reviewers (will set after PR creation)
Tests (script tested manually, workflow will be validated on next release/sync)
Documentation (comprehensive CARTO_CLAUDE.md updates + project docs)

Testing Notes

Script validation:

# Tested version calculation from history:
./.github/scripts/calculate_carto_version.sh "" "1.79.1"
# Output: v1.79.1-carto.1.7.1 ✓

# Analyzed commits:
# - 7 features (MINOR bumps)
# - 9 fixes (PATCH bumps)
# - Correctly excluded sync/merge commits
# - Correctly filtered CARTO authors only

YAML validation: Both workflows validated successfully with Python yaml parser ✓

Commit history fix: Logic verified by code review. Will be validated end-to-end on next sync run.

End-to-end validation: Will be completed when next CARTO release and sync are triggered.

SLACK_KEY secret: Must be verified in repository settings before Slack notifications will work.

Related Files

.github/scripts/calculate_carto_version.sh (NEW) - Version calculator
.github/workflows/carto_release.yaml - Release workflow with new versioning
.github/workflows/carto-upstream-sync.yml - Sync workflow with Slack fixes + history preservation
CARTO_CLAUDE.md - Versioning strategy documentation
~/Documents/claude-projects/litellm-upstream-sync/commit-history-preservation.md - Technical deep dive

Technical Details: Commit History Fix

Before (Broken):

git reset --hard upstream/main  # Creates new commits with different SHAs
git push --force-with-lease     # Force-pushes divergent history

Result: GitHub doesn't recognize commits as shared (shows 3000+ behind)

After (Fixed):

git merge upstream/main -X theirs  # Preserves upstream commit SHAs
# If conflicts:
for file in $CONFLICTS; do
  git checkout --theirs "$file"  # Resolve within merge structure
done
git push origin main  # Normal push (no force needed)

Result: All upstream commits included with original SHAs → GitHub recognizes shared history

Next sync will automatically repair the broken history (brings in all 3000 missing commits with proper lineage)

## Versioning Strategy **New Format:** `v{upstream}-carto.{MAJOR}.{MINOR}.{PATCH}` Example: `v1.79.1-carto.1.7.1` - upstream: 1.79.1 (base LiteLLM version) - CARTO: 1.7.1 (cumulative semantic version) ### Key Features: - ✅ CARTO version accumulates over time (never resets) - ✅ Tracks BREAKING/feat/fix commits using conventional commits - ✅ Only counts commits from @carto.com/@cartodb.com authors - ✅ Upstream syncs keep CARTO version, update upstream base - ✅ Auto-calculates version from commit history ### Version Calculation Script - `.github/scripts/calculate_carto_version.sh` - Analyzes commits since last release - Applies semantic versioning rules chronologically - Filters by CARTO authors, excludes upstream syncs ### Initial Version Based on commit analysis: `v1.79.1-carto.1.7.1` - 7 features (feat:) - 9 fixes (fix:) - 0 breaking changes ## Release Workflow Enhancements 1. **Upstream Sync Detection** - Auto-detects if release is first for new upstream version - Passes `is_upstream_sync` flag to Claude - Enables intelligent release notes generation 2. **Improved Version Calculation** - Removed flawed semver-generator (was counting ALL repo commits) - Uses custom bash script that respects upstream version scope - Accurate version bumps based on actual CARTO changes 3. **Enhanced Claude Prompt** - Receives upstream sync context - Separates CARTO-specific changes from upstream improvements - Auto-generates upstream release comparison section ## Slack Notifications (Fixed & Added) ### Sync Workflow Fix - **Added**: Error handling with 3 retry attempts - **Added**: Slack API response validation - **Added**: Detailed logging and debug info - **Added**: Secret existence check - **Fixed**: No more silent failures ### Release Workflow (NEW) - **Added**: Slack notification after successful release - **Message includes**: - Release type (Upstream Sync vs CARTO Customization) - Release tag and CARTO version - Links to GitHub release and Docker image - **Channel**: infrastructure-dev (C3W6342EN) ### Notification Format Examples: **Sync PR:** ``` 🔄 LiteLLM Upstream Sync - v1.79.1 • PR created: [link] • Commits: 234 ahead • Files changed: 156 ``` **Release (Upstream Sync):** ``` 🔄 LiteLLM CARTO Release - v1.79.1-carto.1.7.1 • Type: Upstream Sync (v1.75.2 → v1.79.1) • CARTO Version: 1.7.1 • Release: [link] • Docker: ghcr.io/cartodb/litellm-non_root:carto-stable ``` **Release (CARTO Customization):** ``` 🚀 LiteLLM CARTO Release - v1.79.1-carto.1.7.2 • Type: CARTO Customization • CARTO Version: 1.7.2 • Release: [link] • Docker: ghcr.io/cartodb/litellm-non_root:carto-stable ``` ## Documentation Updates ### CARTO_CLAUDE.md - **Added**: Complete versioning strategy section - **Added**: Conventional commits guidelines - **Added**: Examples of proper commit messages - **Added**: Version calculation explanation - **Added**: Best practices for commits ### Key Guidelines for Team: - **`feat:`** → MINOR bump (new features) - **`fix:`** → PATCH bump (bug fixes) - **`BREAKING CHANGE:`** → MAJOR bump (breaking changes) - Commit messages must be clear and follow conventional format - Only CARTO author commits count toward versioning ## Benefits 1. **Clear version tracking**: Know exactly how many CARTO customizations exist 2. **Automatic versioning**: No manual version decisions needed 3. **Better release notes**: Separate CARTO vs upstream changes 4. **Team awareness**: Slack notifications keep everyone informed 5. **Conventional commits**: Forces good commit hygiene 6. **Long-term maintainability**: Sustainable as fork continues to diverge ## Migration **Current incorrect release:** `carto-v1.79.1-1.74.336` (wrong calculation) **Correct first release:** `v1.79.1-carto.1.7.1` (from history) Next release will use the new format. ## Testing Pre-commit testing done: - ✅ Version script calculates correctly - ✅ CARTO author filtering works - ✅ Workflow syntax valid - ✅ Documentation complete End-to-end testing: Will be validated on next release workflow run.

- Update Slack channel to C09K0M5MP7V (cartodb-ops) in both workflows - Fix YAML formatting issue in release workflow (multi-line MESSAGE) - Add LiteLLM context to release notifications - Enhance sync notifications with action-required labels and context - Improve notification readability with structured format

mateo-di added 2 commits November 18, 2025 14:55

mateo-di self-assigned this Nov 22, 2025

mateo-di marked this pull request as draft November 22, 2025 01:28

mateo-di changed the title ~~feat: implement CARTO semantic versioning and fix Slack notifications~~ feat: implement semantic versioning and fix upstream sync + Slack notifications Nov 22, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: implement semantic versioning and fix upstream sync + Slack notifications #35

feat: implement semantic versioning and fix upstream sync + Slack notifications #35

Uh oh!

mateo-di commented Nov 20, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: implement semantic versioning and fix upstream sync + Slack notifications #35

Are you sure you want to change the base?

feat: implement semantic versioning and fix upstream sync + Slack notifications #35

Uh oh!

Conversation

mateo-di commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary of Changes

1. CARTO Semantic Versioning Strategy

2. Version Calculation Script

3. Release Workflow Improvements

4. Sync Workflow Slack Fixes

5. Upstream Commit History Preservation (New)

6. Slack Notification Enhancements

7. Documentation

Type of change

Acceptance

Context

Basic checklist

Testing Notes

Related Files

Technical Details: Commit History Fix

Before (Broken):

After (Fixed):

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mateo-di commented Nov 20, 2025 •

edited

Loading