Release Management & Versioning Strategy #945
Replies: 3 comments 4 replies
-
TL;DR
Updated Strategy: Patterns from Major OSS ProjectsAfter reviewing how Kubernetes, Node.js, Python, and Go manage releases, here is a refined strategy grounded in proven OSS practice. The Universal Rule Across All Major Projects
Recommendation for CAIPE: Branch ModelgitGraph
commit id: "feat: LiteLLM"
commit id: "feat: dynamic agents"
commit id: "feat: webex-bot"
branch release/0.3.x
checkout release/0.3.x
commit id: "tag: 0.3.0-rc.1" tag: "v0.3.0-rc.1"
commit id: "cherry-pick: fix slack warnings"
commit id: "tag: 0.3.0-rc.2" tag: "v0.3.0-rc.2"
commit id: "tag: 0.3.0" tag: "v0.3.0"
checkout main
commit id: "feat: 0.4.0 work starts"
checkout release/0.3.x
commit id: "cherry-pick: fix ui crash"
commit id: "tag: 0.3.1" tag: "v0.3.1"
checkout main
merge release/0.3.x id: "backport fixes to main"
Key rules (same as Kubernetes and Node.js):
Feature Freeze & Release Timelinegantt
title CAIPE Release Timeline (Kubernetes-style)
dateFormat YYYY-MM-DD
section main (0.3.x work)
Feature development :a1, 2026-02-01, 42d
Feature freeze (no new feat PRs to milestone) :milestone, 2026-03-14, 0d
section release/0.3.x
Cut branch + tag rc.1 :b1, 2026-03-14, 7d
Cherry-picks + tag rc.2 :b2, 2026-03-21, 7d
Final testing + tag 0.3.0 :b3, 2026-03-28, 7d
section Patches
0.3.1 0.3.2 as needed :c1, 2026-04-04, 30d
Cherry-Pick RC Strategy with GitHub ActionsThis is the mechanism Kubernetes uses with The iron rule (same across all major OSS):
Label-Driven Automation Flowflowchart TD
A[PR merged to main] --> B{cherry-pick label present?}
B -- "cherry-pick/release-0.3.x" --> C[GHA cherry-pick workflow triggers]
B -- No label --> D[Stays on main only]
C --> E{Cherry-pick applies cleanly?}
E -- Yes --> F[Bot opens PR to release/0.3.x]
E -- Conflict --> G[Bot comments conflict warning\non original PR]
F --> H[Reviewer merges to release/0.3.x]
G --> I[Author resolves manually]
H --> J{In RC window?}
J -- Yes --> K[Included in next RC tag]
J -- No, post-release --> L[Included in next patch 0.3.1]
GitHub Actions — Cherry-Pick Workflow# .github/workflows/cherry-pick.yml
name: Cherry-pick to release branch
on:
pull_request:
types: [closed]
branches: [main]
jobs:
cherry-pick:
if: github.event.pull_request.merged == true
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
- name: Find cherry-pick target branches from labels
id: labels
run: |
echo '${{ toJson(github.event.pull_request.labels) }}' \
| jq -r '.[].name | select(startswith("cherry-pick/")) | ltrimstr("cherry-pick/")' \
> /tmp/target-branches.txt
cat /tmp/target-branches.txt
- name: Cherry-pick to each target branch
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
SHA="${{ github.event.pull_request.merge_commit_sha }}"
PR="${{ github.event.pull_request.number }}"
TITLE="${{ github.event.pull_request.title }}"
while IFS= read -r branch; do
[ -z "$branch" ] && continue
NEW_BRANCH="cherry-pick/${PR}-to-${branch//\//-}"
git fetch origin "$branch"
git checkout -b "$NEW_BRANCH" "origin/$branch"
if git cherry-pick "$SHA"; then
git push origin "$NEW_BRANCH"
gh pr create \
--base "$branch" \
--head "$NEW_BRANCH" \
--title "cherry-pick: $TITLE" \
--body "Automated cherry-pick of #${PR} onto \`${branch}\`."
else
git cherry-pick --abort
gh pr comment "$PR" \
--body ":warning: Cherry-pick to \`${branch}\` has conflicts. Manual backport required."
fi
done < /tmp/target-branches.txt
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}GitHub Actions — RC Tagging Workflow# .github/workflows/tag-rc.yml
name: Tag Release Candidate
on:
workflow_dispatch:
inputs:
version:
description: "RC version e.g. 0.3.0-rc.2"
required: true
branch:
description: "Release branch e.g. release/0.3.x"
required: true
jobs:
tag-rc:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ inputs.branch }}
- name: Tag and push RC
run: |
git tag ${{ inputs.version }}
git push origin ${{ inputs.version }}
- name: Create GitHub pre-release with auto-generated notes
run: |
gh release create ${{ inputs.version }} \
--prerelease \
--title "Release Candidate ${{ inputs.version }}" \
--generate-notes \
--target ${{ inputs.branch }}
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}What Qualifies for Cherry-Pick (OSS Consensus)
Should Large Features Target Release Branches?No. This is universal across all major OSS projects. Large features target For CAIPE specifically, given the active flowchart LR
F1[prebuild/feat/webex-bot] --> N[next/0.3.0]
F2[prebuild/feat/slack-authz] --> N
F3[prebuild/fix/metadata-leak] --> N
N -->|CI green, milestone 80%| M[main]
M -->|cut| R[release/0.3.x]
R -->|tag| T1[v0.3.0-rc.1]
T1 -->|cherry-picks + testing| T2[v0.3.0]
Proposed LabelsAdd these to the repo to enable the automation above:
References: Kubernetes release process, Node.js release process, Python release schedule, Go release policy |
Beta Was this translation helpful? Give feedback.
-
CI/CD Versioning Matrix & Release DecisionsVersioning MatrixThe following table defines how chart versions, appVersions, and image versions are managed across different release scenarios:
Decisions
|
Beta Was this translation helpful? Give feedback.
-
|
A few points I'd like to make:
|
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Release Management & Versioning Strategy
Overview
This discussion establishes a comprehensive release management framework for the CAIPE (Community AI Platform Engineering) project, ensuring consistent, predictable, and well-documented releases.
1. Semantic Versioning (SemVer) Framework
Format
Example versions:
0.2.35- Production release0.3.0- Major feature release0.2.35-rc.1- Release candidateVersion Components
2. Release Types & Contents
MAJOR Releases
Frequency: As needed (typically 6-12 months)
What goes in:
MINOR Releases (Monthly Proposed)
Frequency: Monthly
What goes in:
Recent Examples:
PATCH Releases
Frequency: As needed (weekly or bi-weekly)
What goes in:
Recent Examples:
3. Current Release Cadence & Milestones
Active Milestones
Recent Releases
4. Proposed Release Schedule
Monthly Release Cadence
5. Release Process Workflow
Phase 1: Planning
Phase 2: Development
Phase 3: Testing & QA
Phase 4: Release
Phase 5: Post-Release
6. Issue Categorization Guidelines
Labels for Release Planning
Milestone Assignment Rules
7. Milestone Tracking Strategy
Milestone Health Metrics
Milestone Closure Criteria
8. Release Checklist
Pre-Release (1 week before)
Release Day
Post-Release (24 hours)
9. Discussion Prompts for Team Agreement
Questions for Team Discussion
Release Cadence
Version Numbering
Breaking Changes
Release Candidates
Automation
Communication
Hotfixes
Milestone Planning
10. Next Steps
Created: 2026-03-10
Status: 🟡 Open for Discussion
Created by: @sriaradhyula
Beta Was this translation helpful? Give feedback.
All reactions