From 3f6b0597f138654c53bc2f5a0f9bd871882a6339 Mon Sep 17 00:00:00 2001
From: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Date: Fri, 19 Dec 2025 18:11:43 +0000
Subject: [PATCH] docs: update CONTRIBUTING with v2 branching strategy (#1804)

---
 CONTRIBUTING.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c18937f5..dd60f39c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -23,9 +23,14 @@ uv tool install pre-commit --with pre-commit-uv --force-reinstall
 ## Development Workflow
 
 1. Choose the correct branch for your changes:
-   - For bug fixes to a released version: use the latest release branch (e.g. v1.1.x for 1.1.3)
-   - For new features: use the main branch (which will become the next minor/major version)
-   - If unsure, ask in an issue first
+
+   | Change Type | Target Branch | Example |
+   |-------------|---------------|---------|
+   | New features, breaking changes | `main` | New APIs, refactors |
+   | Security fixes for v1 | `v1.x` | Critical patches |
+   | Bug fixes for v1 | `v1.x` | Non-breaking fixes |
+
+   > **Note:** `main` is the v2 development branch. Breaking changes are welcome on `main`. The `v1.x` branch receives only security and critical bug fixes.
 
 2. Create a new branch from your chosen base branch