Skip to content

docs: switch to dual merge strategy #1119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GrammaTonic merged 1 commit into from
Mar 1, 2026
Merged

docs: switch to dual merge strategy #1119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 17 additions & 10 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,28 +295,35 @@ docker compose -f docker/docker-compose.chrome.yml up -d --scale github-runner-c

**CRITICAL**: Direct pushes to `main` and `develop` are blocked by branch protection rules.

### Post-Merge Back-Sync Workflow
### Merge Strategy

After merging a PR from `develop` to `main` with squash merge:
**This repository uses a DUAL merge strategy:**
- **Feature branches → `develop`**: **Squash merge** (one clean commit per feature)
- **`develop` → `main`**: **Regular merge** (preserves shared history, no back-sync needed)

**Why this approach?**
- Squash merging features into `develop` keeps one commit per feature/fix
- Regular merging `develop` → `main` preserves commit ancestry so no back-sync is needed
- No post-merge back-sync step eliminates an entire class of errors

**How to merge:**
```bash
# Sync develop with main to prevent "ahead" status
git checkout develop
git pull origin develop
git merge main -m "chore: sync develop with main after squash merge"
git push origin develop
# Feature branch → develop (SQUASH merge):
gh pr merge <PR_NUMBER> --squash --delete-branch --body "<brief summary>"

# This triggers CI/CD validation on develop branch
# Ensures develop stays in sync with main after squash merges
# develop → main (REGULAR merge — do NOT squash):
gh pr merge <PR_NUMBER> --merge --body "Promote develop to main"
```

**ℹ️ No back-sync needed!** Because `develop` → `main` uses a regular merge (not squash), both branches share the same commit history. There is no divergence after merging.

### Dependabot Automation (ZERO-TOUCH UPDATES)

The repository has fully automated dependency management:

**Auto-Merge Workflow** (`.github/workflows/dependabot-auto-merge.yml`):
- Automatically approves Dependabot PRs
- Enables auto-merge with squash strategy
- Enables auto-merge with squash strategy (Dependabot PRs target `develop`)
- Merges after all CI checks pass
- To disable for specific PR: `gh pr merge <PR_NUMBER> --disable-auto`

Expand Down
111 changes: 20 additions & 91 deletions .github/instructions/pull-request.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,18 @@ description: 'Comprehensive pull request template and instructions for copilot-a

### 🔀 Merge Strategy

**This repository uses SQUASH MERGE as the standard merge strategy.**

**Why Squash Merge?**
- ✅ **Clean, linear commit history** on `main` branch - easier to understand project evolution
- ✅ **One commit per feature/fix** - easier rollbacks and cherry-picking
- ✅ **Better release notes** - automated changelog generation from squashed commits
- ✅ **Simplified CI/CD** - cleaner git history for automated release processes
- ✅ **Consistent with Dependabot** - auto-merge configuration uses squash strategy
- ✅ **Reduced noise** - no "fix typo" or "address review comments" commits in main
- ✅ **Easier bisecting** - each commit represents a complete, logical change
**This repository uses a DUAL merge strategy:**
- **Feature branches → `develop`**: **Squash merge** (one clean commit per feature)
- **`develop` → `main`**: **Regular merge** (preserves shared history, no back-sync needed)

**Why this approach?**
- ✅ **Clean integration branch** - squash merging features into `develop` keeps one commit per feature/fix
- ✅ **No back-sync required** - regular merging `develop` → `main` preserves commit ancestry
- ✅ **Easier rollbacks** - each squashed commit on `develop` represents a complete, logical change
- ✅ **Better release notes** - automated changelog generation from squashed commits on `develop`
- ✅ **Simplified workflow** - no post-merge back-sync step eliminates an entire class of errors
- ✅ **Reduced noise** - no "fix typo" or "address review comments" commits on `develop`
- ✅ **Consistent Dependabot** - auto-merge uses squash strategy for PRs targeting `develop`

**How to Create a PR (Recommended):**
```bash
Expand All @@ -33,18 +35,17 @@ gh pr create --base main --head develop --title "chore: promote develop to main"

**How to Merge (Recommended):**
```bash
# Via GitHub CLI (recommended - ensures squash merge):
gh pr merge <PR_NUMBER> --squash --delete-branch --body "Squash merge: <brief summary>"
# Feature branch → develop (SQUASH merge):
gh pr merge <PR_NUMBER> --squash --delete-branch --body "<brief summary>"

# develop → main (REGULAR merge — do NOT squash):
gh pr merge <PR_NUMBER> --merge --body "Promote develop to main"

# Via GitHub Web UI:
# 1. Click "Squash and merge" button (NOT "Merge pull request" or "Rebase and merge")
# 2. Edit the commit message if needed
# 3. Confirm the merge
# 4. Delete the branch
# Feature → develop: Click "Squash and merge"
# develop → main: Click "Merge pull request" (NOT squash)
```

**⚠️ CRITICAL: After squash merging to `main`, you MUST back-sync `develop`** (see Post-Merge Back-Sync section below).

### ⚠️ Pre-Submission Checklist

<!-- CRITICAL: Complete these steps BEFORE creating this PR -->
Expand Down Expand Up @@ -73,79 +74,7 @@ git checkout <your-feature-branch>
git rebase develop # or 'main' depending on your target branch
```

**Post-Merge Back-Sync (CRITICAL after squash merging to main):**

**⚠️ MANDATORY STEP - DO NOT SKIP THIS!**

**Why is this needed?**
When you squash merge a PR from `develop` to `main`, the individual commits from `develop` are condensed into a single commit on `main`. This causes `develop` to appear "ahead" of `main` in git history, even though the code is identical. The back-sync merge resolves this divergence and prevents:
- ❌ Incorrect "X commits ahead" status on `develop`
- ❌ Merge conflicts on subsequent PRs
- ❌ CI/CD pipeline confusion
- ❌ Duplicate commits in future merges

**When to perform back-sync:**
- ✅ **ALWAYS** after merging a promotion PR (`develop` → `main`) with squash merge
- ✅ **ALWAYS** after merging any PR directly to `main` with squash merge
- ✅ **IMMEDIATELY** after the squash merge completes (don't wait!)
- ❌ NOT needed when merging feature branches to `develop` (develop will be promoted later)

**How to perform back-sync:**
```bash
# Step 1: Ensure your local branches are up-to-date
git fetch --all

# Step 2: Switch to develop and pull latest
git checkout develop
git pull origin develop

# Step 3: Merge main back into develop (creates a merge commit)
git merge main -m "chore: sync develop with main after squash merge"

# Step 4: Push the back-sync to remote
git push origin develop

# This ensures develop stays in sync with main after squash merges
# The merge commit preserves the development history in develop
# while keeping main's linear squashed history
```

**Alternative (using GitHub CLI):**
```bash
# Create a back-sync PR (for teams requiring PR workflow)
git checkout develop
git pull origin develop
git checkout -b chore/backsync-main-to-develop
git merge main -m "chore: sync develop with main after squash merge"
git push origin chore/backsync-main-to-develop
gh pr create --base develop --head chore/backsync-main-to-develop \
--title "chore: back-sync main to develop after squash merge" \
--body "Automatic back-sync after squash merging to main. This prevents 'ahead' status."
gh pr merge --merge --delete-branch # Use regular merge, not squash!
```

**Verification:**
```bash
# After back-sync, these commands should show no differences:
git diff main..develop # Should be empty (no code differences)
git log --oneline main..develop # Should only show merge commits (no unique commits)

# Check branch status (should show "up to date"):
git checkout develop
git status
# Should NOT say "Your branch is ahead of 'origin/develop'"
```

**Troubleshooting:**
```bash
# If you forgot to back-sync and now have conflicts:
git checkout develop
git pull origin develop
git fetch origin main
git merge origin/main -m "chore: late back-sync after squash merge"
# Resolve any conflicts, then:
git push origin develop
```
**ℹ️ No back-sync needed!** Because `develop` → `main` uses a regular merge (not squash), both branches share the same commit history. There is no divergence after merging.

### Summary

Expand Down
111 changes: 20 additions & 91 deletions .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,18 @@

### 🔀 Merge Strategy

**This repository uses SQUASH MERGE as the standard merge strategy.**

**Why Squash Merge?**
- ✅ **Clean, linear commit history** on `main` branch - easier to understand project evolution
- ✅ **One commit per feature/fix** - easier rollbacks and cherry-picking
- ✅ **Better release notes** - automated changelog generation from squashed commits
- ✅ **Simplified CI/CD** - cleaner git history for automated release processes
- ✅ **Consistent with Dependabot** - auto-merge configuration uses squash strategy
- ✅ **Reduced noise** - no "fix typo" or "address review comments" commits in main
- ✅ **Easier bisecting** - each commit represents a complete, logical change
**This repository uses a DUAL merge strategy:**
- **Feature branches → `develop`**: **Squash merge** (one clean commit per feature)
- **`develop` → `main`**: **Regular merge** (preserves shared history, no back-sync needed)

**Why this approach?**
- ✅ **Clean integration branch** - squash merging features into `develop` keeps one commit per feature/fix
- ✅ **No back-sync required** - regular merging `develop` → `main` preserves commit ancestry
- ✅ **Easier rollbacks** - each squashed commit on `develop` represents a complete, logical change
- ✅ **Better release notes** - automated changelog generation from squashed commits on `develop`
- ✅ **Simplified workflow** - no post-merge back-sync step eliminates an entire class of errors
- ✅ **Reduced noise** - no "fix typo" or "address review comments" commits on `develop`
- ✅ **Consistent Dependabot** - auto-merge uses squash strategy for PRs targeting `develop`

**How to Create a PR (Recommended):**
```bash
Expand All @@ -27,18 +29,17 @@ gh pr create --base main --head develop --title "chore: promote develop to main"

**How to Merge (Recommended):**
```bash
# Via GitHub CLI (recommended - ensures squash merge):
gh pr merge <PR_NUMBER> --squash --delete-branch --body "Squash merge: <brief summary>"
# Feature branch → develop (SQUASH merge):
gh pr merge <PR_NUMBER> --squash --delete-branch --body "<brief summary>"

# develop → main (REGULAR merge — do NOT squash):
gh pr merge <PR_NUMBER> --merge --body "Promote develop to main"

# Via GitHub Web UI:
# 1. Click "Squash and merge" button (NOT "Merge pull request" or "Rebase and merge")
# 2. Edit the commit message if needed
# 3. Confirm the merge
# 4. Delete the branch
# Feature → develop: Click "Squash and merge"
# develop → main: Click "Merge pull request" (NOT squash)
```

**⚠️ CRITICAL: After squash merging to `main`, you MUST back-sync `develop`** (see Post-Merge Back-Sync section below).

### ⚠️ Pre-Submission Checklist

<!-- CRITICAL: Complete these steps BEFORE creating this PR -->
Expand Down Expand Up @@ -67,79 +68,7 @@ git checkout <your-feature-branch>
git rebase develop # or 'main' depending on your target branch
```

**Post-Merge Back-Sync (CRITICAL after squash merging to main):**

**⚠️ MANDATORY STEP - DO NOT SKIP THIS!**

**Why is this needed?**
When you squash merge a PR from `develop` to `main`, the individual commits from `develop` are condensed into a single commit on `main`. This causes `develop` to appear "ahead" of `main` in git history, even though the code is identical. The back-sync merge resolves this divergence and prevents:
- ❌ Incorrect "X commits ahead" status on `develop`
- ❌ Merge conflicts on subsequent PRs
- ❌ CI/CD pipeline confusion
- ❌ Duplicate commits in future merges

**When to perform back-sync:**
- ✅ **ALWAYS** after merging a promotion PR (`develop` → `main`) with squash merge
- ✅ **ALWAYS** after merging any PR directly to `main` with squash merge
- ✅ **IMMEDIATELY** after the squash merge completes (don't wait!)
- ❌ NOT needed when merging feature branches to `develop` (develop will be promoted later)

**How to perform back-sync:**
```bash
# Step 1: Ensure your local branches are up-to-date
git fetch --all

# Step 2: Switch to develop and pull latest
git checkout develop
git pull origin develop

# Step 3: Merge main back into develop (creates a merge commit)
git merge main -m "chore: sync develop with main after squash merge"

# Step 4: Push the back-sync to remote
git push origin develop

# This ensures develop stays in sync with main after squash merges
# The merge commit preserves the development history in develop
# while keeping main's linear squashed history
```

**Alternative (using GitHub CLI):**
```bash
# Create a back-sync PR (for teams requiring PR workflow)
git checkout develop
git pull origin develop
git checkout -b chore/backsync-main-to-develop
git merge main -m "chore: sync develop with main after squash merge"
git push origin chore/backsync-main-to-develop
gh pr create --base develop --head chore/backsync-main-to-develop \
--title "chore: back-sync main to develop after squash merge" \
--body "Automatic back-sync after squash merging to main. This prevents 'ahead' status."
gh pr merge --merge --delete-branch # Use regular merge, not squash!
```

**Verification:**
```bash
# After back-sync, these commands should show no differences:
git diff main..develop # Should be empty (no code differences)
git log --oneline main..develop # Should only show merge commits (no unique commits)

# Check branch status (should show "up to date"):
git checkout develop
git status
# Should NOT say "Your branch is ahead of 'origin/develop'"
```

**Troubleshooting:**
```bash
# If you forgot to back-sync and now have conflicts:
git checkout develop
git pull origin develop
git fetch origin main
git merge origin/main -m "chore: late back-sync after squash merge"
# Resolve any conflicts, then:
git push origin develop
```
**ℹ️ No back-sync needed!** Because `develop` → `main` uses a regular merge (not squash), both branches share the same commit history. There is no divergence after merging.

### Summary

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/dependabot-auto-merge.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ jobs:

- name: Enable auto-merge
run: |
# Enable auto-merge with squash merge strategy
# Enable auto-merge with squash strategy (Dependabot PRs target develop)
gh pr merge "${{ github.event.pull_request.number }}" \
--auto --squash \
--subject "chore(deps): ${{ github.event.pull_request.title }}" \
Expand Down
34 changes: 32 additions & 2 deletions docs/features/DEVELOPMENT_WORKFLOW.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,8 +82,38 @@ git push origin feature/your-feature-name
### 4. Release Process

```bash
# When ready for release, create PR: develop → main (maintainers) or tag a release from main
# This triggers production deployment after approval
# When ready for release, create PR: develop → main (maintainers)
# IMPORTANT: Use regular merge (NOT squash) for develop → main
# This preserves commit ancestry and eliminates the need for back-sync
gh pr merge <PR_NUMBER> --merge --body "Promote develop to main"
```

## 🔀 Merge Strategy

**This repository uses a DUAL merge strategy:**

| Direction | Strategy | Reason |
|-----------|----------|--------|
| Feature branch → `develop` | **Squash merge** | One clean commit per feature/fix on `develop` |
| `develop` → `main` | **Regular merge** | Preserves shared commit history, no back-sync needed |
| Dependabot PRs → `develop` | **Squash merge** | Auto-merged with squash (targets `develop` only) |
Comment on lines +95 to +99
Copy link

@gemini-code-assist gemini-code-assist bot Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The new merge strategy documentation is clear for feature branches and promotions from develop to main. However, it omits the merge strategy for hotfix branches, which could lead to confusion.

To make the workflow comprehensive, I suggest explicitly documenting the hotfix merge strategy. A squash merge is likely appropriate to maintain a clean history on main. I've added a row to the table for hotfixes and clarified that a sync to develop is still needed in this case, which is consistent with the hotfix process described elsewhere in this document.

Suggested change
| Direction | Strategy | Reason |
|-----------|----------|--------|
| Feature branch → `develop` | **Squash merge** | One clean commit per feature/fix on `develop` |
| `develop` → `main` | **Regular merge** | Preserves shared commit history, no back-sync needed |
| Dependabot PRs → `develop` | **Squash merge** | Auto-merged with squash (targets `develop` only) |
| Direction | Strategy | Reason |
|-----------|----------|--------|
| Feature branch → `develop` | **Squash merge** | One clean commit per feature/fix on `develop` |
| `develop` → `main` | **Regular merge** | Preserves shared commit history, no back-sync needed |
| Hotfix branch → `main` | **Squash merge** | One clean commit per fix on `main` (requires sync to `develop`) |
| Dependabot PRs → `develop` | **Squash merge** | Auto-merged with squash (targets `develop` only) |


**Key benefits:**
- **No back-sync required** — regular merging `develop` → `main` preserves commit ancestry
- **Clean integration branch** — each feature is a single squashed commit on `develop`
- **Simplified workflow** — no post-merge back-sync step eliminates an entire class of errors

**How to merge:**
```bash
# Feature branch → develop (SQUASH merge):
gh pr merge <PR_NUMBER> --squash --delete-branch --body "<brief summary>"

# develop → main (REGULAR merge — do NOT squash):
gh pr merge <PR_NUMBER> --merge --body "Promote develop to main"

# Via GitHub Web UI:
# Feature → develop: Click "Squash and merge"
# develop → main: Click "Merge pull request" (NOT squash)
```

## 🛡️ Branch Protection Rules
Expand Down
4 changes: 2 additions & 2 deletions docs/features/PROMETHEUS_ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,8 +274,8 @@ gantt
│ Sun-Mon (Dec 20-21): PR & Release │
│ □ TASK-073: Create PR to develop branch │
│ □ TASK-074: Address PR review comments │
│ □ TASK-075: Merge PR with squash merge │
│ □ TASK-076: Perform back-sync (develop ← main) │
│ □ TASK-075: Merge PR with squash merge (to develop) │
│ □ TASK-076: Regular merge develop → main (no back-sync) │
│ □ TASK-077: Tag release v2.3.0 │
│ □ TASK-078: Push tag to origin │
│ □ TASK-079: Create GitHub release with dashboards │
Expand Down
2 changes: 1 addition & 1 deletion plan/feature-prometheus-monitoring-1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ This implementation plan provides a fully executable roadmap for adding Promethe
| TASK-073 | Create PR from `feature/prometheus-improvements` to `develop` with comprehensive description using `.github/pull_request_template.md` | | |
| TASK-074 | Address PR review comments and ensure CI/CD pipeline passes | | |
| TASK-075 | Merge PR to `develop` using squash merge strategy | | |
| TASK-076 | Perform back-sync from `main` to `develop` after merge (if merging to main) | | |
| TASK-076 | Create promotion PR from `develop` → `main` using regular merge (no back-sync needed) | | |
| TASK-077 | Tag release: `git tag -a v2.3.0 -m "Release v2.3.0: Prometheus Metrics & Grafana Dashboards"` | | |
| TASK-078 | Push tag: `git push origin v2.3.0` | | |
| TASK-079 | Create GitHub release with release notes and dashboard JSON attachments | | |
Expand Down