diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0109cc93..343bc199 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -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 --squash --delete-branch --body "" -# 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 --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 --disable-auto` diff --git a/.github/instructions/pull-request.instructions.md b/.github/instructions/pull-request.instructions.md index b82292f6..1067b118 100644 --- a/.github/instructions/pull-request.instructions.md +++ b/.github/instructions/pull-request.instructions.md @@ -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 @@ -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 --squash --delete-branch --body "Squash merge: " +# Feature branch → develop (SQUASH merge): +gh pr merge --squash --delete-branch --body "" + +# develop → main (REGULAR merge — do NOT squash): +gh pr merge --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 @@ -73,79 +74,7 @@ git checkout 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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b267de23..98138c2c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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 @@ -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 --squash --delete-branch --body "Squash merge: " +# Feature branch → develop (SQUASH merge): +gh pr merge --squash --delete-branch --body "" + +# develop → main (REGULAR merge — do NOT squash): +gh pr merge --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 @@ -67,79 +68,7 @@ git checkout 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 diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml index 6879edec..cb5d567d 100644 --- a/.github/workflows/dependabot-auto-merge.yml +++ b/.github/workflows/dependabot-auto-merge.yml @@ -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 }}" \ diff --git a/.github/workflows/seed-trivy-sarif.yml b/.github/workflows/seed-trivy-sarif.yml index 2e84ca5b..51261107 100644 --- a/.github/workflows/seed-trivy-sarif.yml +++ b/.github/workflows/seed-trivy-sarif.yml @@ -12,8 +12,8 @@ # # Triggers: # - Manual: workflow_dispatch with scan type selection -# - Automatic: Push to main branch (production deployments) -# - Scheduled: Weekly on Monday 2 AM UTC +# - Automatic: After CI/CD Pipeline completes on main (workflow_run) +# - Scheduled: Weekly on Monday 4 AM UTC # # Fixes Applied: # - PR #1048: Removed multi-platform build incompatibility with docker exporter @@ -38,8 +38,10 @@ on: - all - filesystem - container - push: - branches: [main] # Only on production deployments + workflow_run: + workflows: ["CI/CD Pipeline"] # Run after CI/CD completes on main — avoids duplicate Trivy scans + types: [completed] + branches: [main] schedule: - cron: '0 4 * * 1' # Weekly deep scan on Monday 4 AM UTC (staggered from maintenance at 2AM, advisories at 3AM) @@ -48,11 +50,20 @@ permissions: security-events: write packages: write +concurrency: + group: trivy-baseline-${{ github.ref }} + cancel-in-progress: true + jobs: seed-filesystem-baseline: name: Seed Trivy filesystem SARIF baseline runs-on: ubuntu-latest - if: github.event.inputs.scan_type == 'filesystem' || github.event.inputs.scan_type == 'all' || github.event_name == 'push' || github.event_name == 'schedule' + # Run on: dispatch (filesystem/all), schedule, or successful CI/CD completion on main + if: | + github.event.inputs.scan_type == 'filesystem' || + github.event.inputs.scan_type == 'all' || + github.event_name == 'schedule' || + (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') steps: - name: Checkout code uses: actions/checkout@v6 @@ -91,7 +102,12 @@ jobs: seed-container-baseline: name: Seed Trivy container SARIF baseline runs-on: ubuntu-latest - if: github.event.inputs.scan_type == 'container' || github.event.inputs.scan_type == 'all' || github.event_name == 'push' || github.event_name == 'schedule' + # Run on: dispatch (container/all), schedule, or successful CI/CD completion on main + if: | + github.event.inputs.scan_type == 'container' || + github.event.inputs.scan_type == 'all' || + github.event_name == 'schedule' || + (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') strategy: matrix: variant: [standard, chrome, chrome-go] @@ -177,8 +193,8 @@ jobs: echo "- \`container-scan-chrome-go\` - Chrome-Go runner container vulnerabilities" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "### Schedule:" >> $GITHUB_STEP_SUMMARY - echo "- 📅 Weekly automated scan: Monday 2 AM UTC" >> $GITHUB_STEP_SUMMARY - echo "- 🚀 Automatic on production deployments (main branch)" >> $GITHUB_STEP_SUMMARY + echo "- 📅 Weekly automated scan: Monday 4 AM UTC" >> $GITHUB_STEP_SUMMARY + echo "- 🚀 Automatic after CI/CD Pipeline succeeds on main (workflow_run)" >> $GITHUB_STEP_SUMMARY echo "- 🔧 Manual trigger available via workflow_dispatch" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "View results in the [Security tab](https://github.com/${{ github.repository }}/security/code-scanning)" >> $GITHUB_STEP_SUMMARY diff --git a/VERSION b/VERSION index 197c4d5c..437459cd 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.4.0 +2.5.0 diff --git a/docs/features/DEVELOPMENT_WORKFLOW.md b/docs/features/DEVELOPMENT_WORKFLOW.md index e9f5f1ac..1549bb38 100644 --- a/docs/features/DEVELOPMENT_WORKFLOW.md +++ b/docs/features/DEVELOPMENT_WORKFLOW.md @@ -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 --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) | + +**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 --squash --delete-branch --body "" + +# develop → main (REGULAR merge — do NOT squash): +gh pr merge --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 diff --git a/docs/features/PROMETHEUS_ROADMAP.md b/docs/features/PROMETHEUS_ROADMAP.md index f54bfc3f..a1993765 100644 --- a/docs/features/PROMETHEUS_ROADMAP.md +++ b/docs/features/PROMETHEUS_ROADMAP.md @@ -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 │ diff --git a/docs/releases/CHANGELOG.md b/docs/releases/CHANGELOG.md index 3b1fb71b..4d7abe54 100644 --- a/docs/releases/CHANGELOG.md +++ b/docs/releases/CHANGELOG.md @@ -2,6 +2,16 @@ ## [Unreleased] +## [v2.5.0] - 2026-03-01 +- Bump GitHub Actions runner to **2.332.0**. +- Optimize CI/CD pipeline for speed and cost — faster builds, reduced runner minutes (#1111). +- Fix critical and high priority security workflow optimizations (#1112). +- Improve maintenance workflow reliability, cache cleanup, and issue automation (#1115). +- Switch to dual merge strategy — squash to develop, regular merge to main (#1119). +- Replace push trigger with `workflow_run` in seed-trivy-sarif workflow (#1118). +- Strip trailing whitespace across YAML workflow files for yamllint compliance. +- Streamline PR template and copilot instructions for dual merge workflow. + ## [v2.4.0] - 2026-03-01 - Update Node.js to **24.14.0** (LTS Krypton) in Chrome and Chrome-Go runners. - Update npm to **11.11.0** in Chrome and Chrome-Go runners. diff --git a/plan/feature-prometheus-monitoring-1.md b/plan/feature-prometheus-monitoring-1.md index 72fd9258..3b064316 100644 --- a/plan/feature-prometheus-monitoring-1.md +++ b/plan/feature-prometheus-monitoring-1.md @@ -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 | | |