Add release branching and cherry picking process

[afritzler]

Summary by CodeRabbit

• New Features

  • Added automated release branch creation when pushing version tags.
  • Introduced cherry-pick tooling to assist with merging fixes into release branches.

• Documentation

  • Reworked navigation: "Concepts" now links to Documentation/Architecture.
  • Renamed "Developer Guide" to "Development."
  • Added a Contributing section with a cherry-picking guide.

• Chores

  • Release notes generation now filters by the current branch/commitish and recognizes release-* branches.

[coderabbitai]

Walkthrough

Adds an automated release-branch creation workflow triggered by version tags, updates release-drafter to filter by commitish and include release branches, adds a cherry-pick automation script with documentation, and updates site navigation/sidebar entries.

Changes

Cohort / File(s)	Summary
GitHub Actions workflows .github/workflows/create-release-branch.yml, .github/workflows/release-drafter.yml	Adds a workflow to create a release branch from pushed semver tags; expands release-drafter triggers to include release-** branches and enables filter-by-commitish.
Release tooling script hack/cherry-pick.sh	New executable Bash script to cherry-pick a merged PR into a specified release branch, validate prerequisites, handle conflicts, push a branch, and open a PR via the GitHub CLI.
Documentation and site config docs/.vitepress/config.mts, docs/contributing/cherry_pick.md	Updates navigation/sidebar labels and adds a new contributing guide page documenting the cherry-pick workflow and usage examples for hack/cherry-pick.sh.

Sequence Diagram(s)

sequenceDiagram
    actor Developer
    participant Git
    participant GitHub
    participant Actions as "GitHub Actions"
    participant Origin as "Origin (remote)"

    Developer->>Git: Push tag vX.Y.Z
    Git->>GitHub: Push tag
    GitHub->>Actions: Trigger workflow on tag
    Actions->>Actions: Extract tag, derive release branch name
    Actions->>Origin: Create & push release-vX.Y branch
    Origin->>GitHub: New branch available
    GitHub-->>Developer: Release branch created

Loading

sequenceDiagram
    actor Developer
    participant Script as "hack/cherry-pick.sh"
    participant Git as "git"
    participant GH as "gh (GitHub CLI)"
    participant Origin as "Origin (remote)"
    participant GitHub as "GitHub"

    Developer->>Script: ./hack/cherry-pick.sh <PR#> release-vX.Y
    Script->>Git: Verify working tree clean & fetch
    Script->>GH: Query PR merge commit and title
    GH-->>Script: Return commit hash & title
    Script->>Git: Create cherry-pick branch from origin/release
    Script->>Git: git cherry-pick -m1 <commit>
    alt conflicts
        Script-->>Developer: Prompt to resolve conflicts and continue
        Developer->>Git: Resolve conflicts and git cherry-pick --continue
    end
    Script->>Origin: Push cherry-pick branch
    Script->>GitHub: Open PR via gh
    GitHub-->>Developer: PR opened targeting release branch

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is completely missing; no description content was provided despite the repository template requiring a 'Proposed Changes' section with specific items and issue references.	Add a comprehensive description following the template: include bullet points under 'Proposed Changes' detailing the workflow automation, documentation, and cherry-pick script additions, and reference any related issues with 'Fixes #'.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main changes: introducing release branching automation and cherry-picking capabilities across multiple workflow and documentation files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch enh/release-branches

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

hack/cherry-pick.sh (2)

46-52: Consider combining the two gh pr view calls into one.

Two separate API calls are made to fetch mergeCommit and title. These can be combined to reduce API calls.

♻️ Proposed optimization

-MERGE_COMMIT=$(gh pr view "${PR_NUMBER}" --json mergeCommit --jq '.mergeCommit.oid')
-if [[ -z "${MERGE_COMMIT}" ]]; then
-    echo "Error: PR #${PR_NUMBER} has no merge commit. Is it merged?"
-    exit 1
-fi
-
-PR_TITLE=$(gh pr view "${PR_NUMBER}" --json title --jq '.title')
+PR_JSON=$(gh pr view "${PR_NUMBER}" --json mergeCommit,title)
+MERGE_COMMIT=$(echo "${PR_JSON}" | jq -r '.mergeCommit.oid // empty')
+if [[ -z "${MERGE_COMMIT}" ]]; then
+    echo "Error: PR #${PR_NUMBER} has no merge commit. Is it merged?"
+    exit 1
+fi
+PR_TITLE=$(echo "${PR_JSON}" | jq -r '.title')

Note: this introduces a dependency on jq, so alternatively you could keep two calls if you want to avoid that.

---

64-64: git switch -c will fail if the branch already exists locally.

If a previous cherry-pick attempt left behind the local branch (e.g., user resolved conflicts but didn't clean up), this line will error out with a somewhat opaque git message. Consider using git switch -C (uppercase) to force-reset the branch, or add a check/cleanup hint.

♻️ Proposed fix

-git switch -c "${CHERRY_PICK_BRANCH}" "origin/${RELEASE_BRANCH}"
+git switch -C "${CHERRY_PICK_BRANCH}" "origin/${RELEASE_BRANCH}"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/release-drafter.yml:
- Around line 28-29: In the workflow for release-drafter/release-drafter@v6
remove the invalid input filter-by-commitish and keep only commitish: ${{
github.ref_name }}, then add filter-by-commitish: true to the release-drafter
configuration file (the .release-drafter.yml config used by release-drafter) so
the filter-by-commitish key is defined in the config (not the workflow) to
enable branch-target filtering.

🧹 Nitpick comments (2)

hack/cherry-pick.sh (2)

60-64: Re-running the script after a failure will fail at git switch -c if the local branch already exists.

If a previous attempt partially completed (e.g., conflicts), the user resolves and retries from scratch, git switch -c will refuse to create the branch. Consider either deleting the existing local branch first or switching to git switch -C (force-create).

Proposed fix

-git switch -c "${CHERRY_PICK_BRANCH}" "origin/${RELEASE_BRANCH}"
+git switch -C "${CHERRY_PICK_BRANCH}" "origin/${RELEASE_BRANCH}"

---

45-52: Two separate gh API calls could be combined into one.

Minor optimization — both mergeCommit.oid and title can be fetched in a single gh pr view call.

Proposed optimization

-MERGE_COMMIT=$(gh pr view "${PR_NUMBER}" --json mergeCommit --jq '.mergeCommit.oid')
-if [[ -z "${MERGE_COMMIT}" ]]; then
-    echo "Error: PR #${PR_NUMBER} has no merge commit. Is it merged?"
-    exit 1
-fi
-
-PR_TITLE=$(gh pr view "${PR_NUMBER}" --json title --jq '.title')
+PR_DATA=$(gh pr view "${PR_NUMBER}" --json mergeCommit,title)
+MERGE_COMMIT=$(echo "${PR_DATA}" | jq -r '.mergeCommit.oid')
+if [[ -z "${MERGE_COMMIT}" || "${MERGE_COMMIT}" == "null" ]]; then
+    echo "Error: PR #${PR_NUMBER} has no merge commit. Is it merged?"
+    exit 1
+fi
+PR_TITLE=$(echo "${PR_DATA}" | jq -r '.title')

Note: this adds a jq dependency, so the simpler two-call approach is also fine.

[xkonni]

looks good.