1

Branching Model

github-actions[bot] edited this page 2026-07-29 18:19:12 +00:00

Table of Contents

• Branching & Release Model
• At a glance
• Where should my PR target?
• Release freeze (parallel cycles)
• Why both a branch and a tag?
• Related docs

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

🌍 View in other languages

Branching & Release Model

OmniRoute uses a parallel-cycle release model: a dedicated release/vX.Y.Z branch for the active cycle, main for the published line, and an immutable vX.Y.Z tag when that cycle ships. Seeing commits land on release/* and on main is expected — not a mix-up.

Maintainer detail lives in CLAUDE.md (Hard Rule #21) and RELEASE_CHECKLIST.md. This page is the public contributor-facing summary.

At a glance

Ref	Role
release/vX.Y.Z	Active cycle — day-to-day development and PR merges for that version
main	Published line — receives the cycle via squash-merge when the release ships
vX.Y.Z (tag)	Ship marker — immutable “what shipped” pointer cut at release time

flowchart LR
  A["feat/fix branch"] --> B["PR → release/vX.Y.Z"]
  B --> C["release/vX.Y.Z tip"]
  C --> D["Release PR squash-merges → main"]
  D --> E["Tag vX.Y.Z"]
  C --> F["Next cycle: release/vX+1 cut from frozen tip"]

Where should my PR target?

Target the active release/vX.Y.Z branch — not main.

1. Find the highest open release/v* branch (example at the time of writing: release/v3.8.49).
2. Branch from that tip (git fetch + checkout / rebase onto it).
3. Open the PR with base = that release/vX.Y.Z.

main is not the day-to-day integration branch. PRs opened against main usually need retargeting before merge.

Release freeze (parallel cycles)

When a release is being reconciled, a marker issue labeled release-freeze is opened. That does not stop development:

• The frozen release/vX.Y.Z belongs to the release captain for that ship.
• The next cycle’s release/vX+1 is cut from the frozen tip so contributors keep landing work.
• Open PRs that still target the frozen branch should be retargeted to the active (highest) release/v* branch.

Check for an open freeze before assuming the branch you want is mergeable:

gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open

Merge mechanics (owner queue label → Mergify) are documented in MERGE_TRAIN.md.

Why both a branch and a tag?

Artifact	Lifetime	Purpose
release/vX.Y.Z	In-flight cycle	Collects reviewed PRs, stays CI-green, is the PR base
Tag vX.Y.Z	Forever	Marks the exact bits that shipped to npm / GitHub Releases

The branch is the workshop; the tag is the sealed package. After squash-merge to main, the next cycle continues on release/vX+1 without waiting for the prior release PR to finish.

Related docs

• CONTRIBUTING.md — setup, tests, PR checklist
• RELEASE_CHECKLIST.md — pre-ship validation
• MERGE_TRAIN.md — merge queue and fallback train
• RELEASE_GREEN.md — keeping the release tip green

🏠 Home

🌍 Languages (40+)

---

🚀 Getting Started

• Setup Guide
• User Guide
• Features
• Quick Start (Docker)
• Electron Desktop App
• Termux (Android)
• PWA Guide

🌐 Providers

• Provider Reference
• All Providers
• Free Tiers
• Kiro Setup

🎯 Routing & Combos

• Auto-Combo
• Reasoning Replay

🗜️ Compression

• Compression Guide
• Compression Engines
• RTK Compression
• Language Packs
• Rules Format

🔌 Integrations

• MCP Server
• A2A Server
• Agent Protocols
• OpenCode Plugin
• Webhooks
• Cloud Agents
• Skills
• Memory
• Evals
• Gamification

🏗️ Architecture

• Architecture Overview
• Codebase Documentation
• Repository Map
• Authorization Guide
• Resilience Guide

🔒 Security

• Guardrails
• Compliance
• Error Sanitization
• Public Credentials
• Route Guard Tiers
• Stealth Guide
• CLI Token Auth

📋 Reference

• API Reference
• CLI Tools
• Environment Variables

🚀 Operations

• VM Deployment
• Fly.io Deployment
• Tunnels Guide
• Proxy Guide
• SQLite Runtime
• Coverage Plan
• Release Checklist

ℹ️ More

• Troubleshooting
• i18n / Translations
• Uninstall
• Contributing
• Comparison vs Alternatives

OmniRoute · Website · npm · Docker Hub