#169 - Add feature branching strategy for projects

.github/workflows/docs-deploy.yaml

@@ -20,8 +20,7 @@ name: Docs Deployment
 on:
   # Runs on pushes targeting the main branch
   push:
-    branches:
-      - main
+    branches: [ main ]
     paths:
       - 'docs/**'
       - 'workflows/**'

.github/workflows/helm-chart-lint.yaml

@@ -20,7 +20,7 @@ on:
   workflow_dispatch:
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: [main]
+    branches: [ main, 'feature/**' ]
     paths:
       - 'deployments/charts/**'
       - '.github/workflows/helm-chart-lint.yaml'

.github/workflows/pr-checks.yaml

@@ -20,7 +20,7 @@ on:
   workflow_dispatch:
   pull_request:
     types: [opened, synchronize, reopened, closed]
-    branches: [ main ]
+    branches: [ main, 'feature/**' ]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number }}

.github/workflows/pr-description-check.yaml

@@ -19,7 +19,7 @@ name: PR Description Check
 on:
   pull_request:
     types: [opened, synchronize, reopened, edited]
-    branches: [main]
+    branches: [ main, 'feature/**' ]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number }}

.github/workflows/sync-feature-branches.yaml

@@ -0,0 +1,150 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: Sync Feature Branches
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Run every Monday at 9am PT (5pm UTC)
+    - cron: '0 17 * * 1'
+
+jobs:
+  sync-feature-branches:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all branches and history
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Find and sync feature branches
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -e
+
+          echo "🔍 Finding feature branches..."
+
+          # Get all remote feature branches
+          feature_branches=$(git branch -r | grep 'origin/feature/' | sed 's|origin/||' | grep -v HEAD || true)
+
+          if [ -z "$feature_branches" ]; then
+            echo "ℹ️  No feature branches found matching pattern 'feature/*'"
+            exit 0
+          fi
+
+          echo "Found feature branches:"
+          echo "$feature_branches"
+          echo ""
+
+          # Process each feature branch
+          for branch in $feature_branches; do
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "📋 Processing branch: $branch"
+
+            # Check if main has commits not in the feature branch
+            git fetch origin main
+            git fetch origin "$branch"
+
+            commits_behind=$(git rev-list --count origin/$branch..origin/main)
+
+            if [ "$commits_behind" -eq 0 ]; then
+              echo "✅ Branch $branch is already up to date with main"
+              continue
+            fi
+
+            echo "📊 Branch $branch is $commits_behind commit(s) behind main"
+
+            # Extract issue number from branch name (format: feature/PROJ-NNN-short-slug)
+            # If no PROJ-NNN pattern is found, use "Issue - None"
+            issue_number=$(echo "$branch" | grep -oE 'PROJ-[0-9]+' || echo "")
+            if [ -z "$issue_number" ]; then
+              issue_ref="Issue - None"
+            else
+              issue_ref="Issue #$issue_number"
+            fi
+
+            # Create a temporary branch for the merge
+            temp_branch="sync/$branch/$(date +%Y%m%d-%H%M)"
+
+            echo "🌿 Creating temporary branch: $temp_branch"
+            git checkout -b "$temp_branch" "origin/$branch"
+
+            # Attempt to merge main
+            echo "🔀 Merging main into $temp_branch..."
+            if git merge origin/main --no-commit --no-ff; then
+              echo "✅ Merge successful (no conflicts)"
+            else
+              echo "⚠️  Merge has conflicts - will create PR for manual resolution"
+              git add -A
+              git commit -m "Merge main into $branch"
+            fi
+
+            # Push the temporary branch
+            echo "⬆️  Pushing $temp_branch to remote..."
+            git push origin "$temp_branch"
+
+            # Create PR
+            echo "📝 Creating pull request..."
+
+            gh pr create \
+              --base "$branch" \
+              --head "$temp_branch" \
+              --title "Sync main into $branch" \
+              --body "$(cat <<EOF
+          ## Description
+
+          This automated PR merges the latest changes from \`main\` into \`$branch\`.
+
+          **What to do:**
+          Review the changes and merge this PR to keep your feature branch up to date with main. If there are merge conflicts, resolve them before merging.
+
+          **Branch Info:**
+          - **Target**: \`$branch\`
+          - **Source**: \`main\`
+          - **Commits behind**: $commits_behind
+
+          $issue_ref
+
+          ## Checklist
+          - [ ] I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/OSMO/blob/main/CONTRIBUTING.md).
+          - [ ] New or existing tests cover these changes.
+          - [ ] The documentation is up to date with these changes.
+
+          ---
+          *This PR was automatically created by the [Sync Feature Branches workflow](.github/workflows/sync-feature-branches.yaml) as part of the [Projects Process](../projects/README.md#stage-in-development).*
+          EOF
+            )"
+
+            echo "✅ Created PR to sync main into $branch"
+
+            # Switch back to main for next iteration
+            git checkout main
+
+          done
+
+          echo ""
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          echo "✨ Sync process complete!"

projects/README.md

@@ -125,14 +125,21 @@ For proposals that are significant or complex, a project design document provide
 1. **Create sub-issues** – Break the project into concrete tasks and open sub-issues for each.
    - Use the implementation plan from the project design to organize work.
 
-2. **Submit pull requests** – Implement the project in PRs, linking back to the relevant issues.
-   - Reference the project proposal in PR descriptions for context.
+2. **Track progress** – OSMO team updates the **Stage** field to **Stage: In Development** in the Projects project board.
 
-3. **Update the project design** – As implementation progresses, update the project design document if decisions change or new details emerge.
-   - Submit PRs to update the design document as needed.
+3. **Create a feature branch** - Work in a feature branch to keep `main` clean during feature development.
+   - Create the feature branch with the naming `feature/PROJ-NNN-short-slug`. Use the same name as your [Design (Markdown)](#stage-design-markdown).
+   - If your feature can be completed in a single, reasonably-sized PR, this project process may be unecessary. Use your discretion about whether a feature branch is necessary, and feel free to ask the OSMO team in your proposal issue.
+
+4. **Submit pull requests** – Implement the project in PRs against your feature branch.
+   - Reference the sub-issues in PR descriptions for context.
 
-4. **Track progress** – OSMO team updates the **Stage** field to **Stage: In Development** in the Projects project board.
-   - Create sub-issues and link them to PRs for visibility.
+5. **Merge `main`** - Keep your feature branch compatible with `main` by merging `main` into your feature branch with a PR.
+   - PRs will be opened weekly on Monday by automation to merge the latest `main` into the feature branch.
+   - Resolve any merge conflicts you encounter and merge into your feature branch.
+
+5. **Update the project design** – As implementation progresses, update the project design document if decisions change or new details emerge.
+   - Submit PRs to update the design document as needed.
 
 ### Stage: Shipped