From 13274df87c27ffd5eab227f2d3e3de3911246920 Mon Sep 17 00:00:00 2001
From: Ryan <16667079+mccaffers@users.noreply.github.com>
Date: Sun, 2 Feb 2025 13:04:04 +0000
Subject: [PATCH 1/6] Refactoring the workflow file

---
 .github/workflows/sonarcloud.yml | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml
index e16ec9a..a8a3a74 100644
--- a/.github/workflows/sonarcloud.yml
+++ b/.github/workflows/sonarcloud.yml
@@ -77,25 +77,35 @@ jobs:
       - name: install gcovr 5.0
         run: |
           pip install gcovr==5.0 # 5.1 is not supported by sonarcloud
-      - name: Install sonar-scanner and build-wrapper
-        uses: SonarSource/sonarcloud-github-c-cpp@v3   
+      - name: Install Build Wrapper
+        uses: SonarSource/sonarqube-scan-action/install-build-wrapper@4.2.1
+      # - name: Install sonar-scanner and build-wrapper
+      #   uses: SonarSource/sonarcloud-github-c-cpp@v3   
       - name: Download all workflow run artifacts
         uses: actions/download-artifact@v4
       - name: Unpack Artifact  
         run: >
           ls -l ./
       - name: Configure CMake
-        # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
-      #  See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
         run: cmake -S ${{github.workspace}} -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
       - name: Run build-wrapper
         run: |
           build-wrapper-linux-x86-64 --out-dir ${{ env.BUILD_WRAPPER_OUT_DIR }} cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
-      - name: Run sonar-scanner
+      - name: SonarQube Scan
+        uses: SonarSource/sonarqube-scan-action@4.2.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN  }} # Put the name of your token here
-        run: |
-          sonar-scanner \
-          --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json" \
-          -Dsonar.coverageReportPaths=artifact/sonarqube-generic-coverage.xml
\ No newline at end of file
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN  }} 
+        with:
+          # Consult https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/scanners/sonarscanner/ for more information and options
+          args: >
+            --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json" \
+      #       -Dsonar.coverageReportPaths=artifact/sonarqube-generic-coverage.xml
+      # - name: Run sonar-scanner
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #     SONAR_TOKEN: ${{ secrets.SONAR_TOKEN  }} 
+      #   run: |
+      #     sonar-scanner \
+      #     --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json" \
+      #     -Dsonar.coverageReportPaths=artifact/sonarqube-generic-coverage.xml
\ No newline at end of file

From 65a0ecec12a1d3536716ed784f58a4ee98535746 Mon Sep 17 00:00:00 2001
From: Ryan <16667079+mccaffers@users.noreply.github.com>
Date: Sun, 2 Feb 2025 13:08:09 +0000
Subject: [PATCH 2/6] Missed version number

---
 .github/workflows/sonarcloud.yml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml
index a8a3a74..0e14de7 100644
--- a/.github/workflows/sonarcloud.yml
+++ b/.github/workflows/sonarcloud.yml
@@ -78,7 +78,7 @@ jobs:
         run: |
           pip install gcovr==5.0 # 5.1 is not supported by sonarcloud
       - name: Install Build Wrapper
-        uses: SonarSource/sonarqube-scan-action/install-build-wrapper@4.2.1
+        uses: SonarSource/sonarqube-scan-action/install-build-wrapper@v4.2.1
       # - name: Install sonar-scanner and build-wrapper
       #   uses: SonarSource/sonarcloud-github-c-cpp@v3   
       - name: Download all workflow run artifacts
@@ -92,7 +92,8 @@ jobs:
         run: |
           build-wrapper-linux-x86-64 --out-dir ${{ env.BUILD_WRAPPER_OUT_DIR }} cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
       - name: SonarQube Scan
-        uses: SonarSource/sonarqube-scan-action@4.2.1
+        uses: 
+        uses: SonarSource/sonarqube-scan-action@v4.2.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN  }} 

From dc6b2c25249811db0cbd64cb7e20c86d13a5a3d1 Mon Sep 17 00:00:00 2001
From: Ryan <16667079+mccaffers@users.noreply.github.com>
Date: Sun, 2 Feb 2025 13:10:44 +0000
Subject: [PATCH 3/6] Missed version number

---
 .github/workflows/sonarcloud.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml
index 0e14de7..f5ec19a 100644
--- a/.github/workflows/sonarcloud.yml
+++ b/.github/workflows/sonarcloud.yml
@@ -5,7 +5,7 @@ on:
     branches:
       - main
   pull_request:
-      types: [opened, synchronize, reopened]
+      types: [opened, edited, synchronize, reopened]
 name: Build
 
 env:

From 3af698dd00c6b7a7ca816889032acde037c3ceb7 Mon Sep 17 00:00:00 2001
From: Ryan <16667079+mccaffers@users.noreply.github.com>
Date: Sun, 2 Feb 2025 13:15:35 +0000
Subject: [PATCH 4/6] fixing workflow issue

---
 .github/workflows/sonarcloud.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml
index f5ec19a..d3a18fe 100644
--- a/.github/workflows/sonarcloud.yml
+++ b/.github/workflows/sonarcloud.yml
@@ -92,7 +92,6 @@ jobs:
         run: |
           build-wrapper-linux-x86-64 --out-dir ${{ env.BUILD_WRAPPER_OUT_DIR }} cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
       - name: SonarQube Scan
-        uses: 
         uses: SonarSource/sonarqube-scan-action@v4.2.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

From dc5843cc8b47bd61e9d2a500f6f648dc845f7fcc Mon Sep 17 00:00:00 2001
From: Ryan <16667079+mccaffers@users.noreply.github.com>
Date: Sun, 2 Feb 2025 13:30:43 +0000
Subject: [PATCH 5/6] refactoring the workflow, bumping python and gcovr

---
 .github/workflows/sonarcloud.yml | 98 +++++++++++++++++++-------------
 1 file changed, 57 insertions(+), 41 deletions(-)

diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml
index d3a18fe..b26e7c4 100644
--- a/.github/workflows/sonarcloud.yml
+++ b/.github/workflows/sonarcloud.yml
@@ -1,36 +1,56 @@
+# Workflow for building and testing the project
+name: Build
+
+# Define when the workflow should run
 on:
-  # Trigger analysis when pushing in master or pull requests, and when creating
-  # a pull request.
   push:
     branches:
-      - main
+      - main  # Trigger on pushes to main branch
   pull_request:
-      types: [opened, edited, synchronize, reopened]
-name: Build
+    types: 
+      - opened      # When PR is first created
+      - edited      # When PR description/title is edited
+      - synchronize # When new commits are pushed to the PR
+      - reopened    # When PR is reopened after being closed
 
+# Environment variables used across jobs
 env:
-  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
-  BUILD_TYPE: Release
-  BUILD_WRAPPER_OUT_DIR: build_wrapper_output_directory # Directory where build-wrapper output will be placed
+  BUILD_TYPE: Release  # Set CMake build configuration
+  BUILD_WRAPPER_OUT_DIR: build_wrapper_output_directory  # Output directory for build wrapper
 
 jobs:
-
   build:
     name: Build & Test
-    runs-on: macos-14
+    runs-on: macos-14  # Use macOS 14 (Sonoma) runner
+
     steps:
-    - uses: actions/checkout@v4
+    # Step 1: Check out the repository code
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Step 2: Set up Homebrew package manager
     - name: Set up Homebrew
       id: set-up-homebrew
       uses: Homebrew/actions/setup-homebrew@master
-    - name: Install packages
-      run: >
-          bash ./.github/workflows/brew.sh
+
+    # Step 3: Install required dependencies using Homebrew
+    - name: Install dependencies
+      run: bash ./.github/workflows/brew.sh
+
+    # Step 4: Build project libraries
     - name: Build libraries
-      run: >
-          bash ./.github/workflows/build.sh
-    - name: Select Xcode  
-      run: sudo xcode-select -switch /Applications/Xcode_15.2.app && /usr/bin/xcodebuild -version
+      run: bash ./.github/workflows/build.sh
+
+    # Step 5: Configure Xcode version
+    - name: Select Xcode version
+      run: |
+        sudo xcode-select -switch /Applications/Xcode_15.2.app
+        /usr/bin/xcodebuild -version
+    # Run XCode tests with specific configurations:
+    # - Builds and runs the test suite
+    # - Generates code coverage reports
+    # - Uses PostgreSQL and libpqxx external dependencies
+    # - Outputs results in JUnit format
     - name: Run tests
       run: >
           CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO
@@ -48,13 +68,16 @@ jobs:
     - name: Convert coverage report to sonarqube format
       run: >
           bash ./.github/workflows/xccov-to-sonarqube-generic.sh *.xcresult/ > sonarqube-generic-coverage.xml
+    # Artifact will be available only for 1 day, this is because 
+    # it's only used to pass test data to SonarCloud only
     - name: Upload coverage report
       uses: actions/upload-artifact@v4
       with:
         path: sonarqube-generic-coverage.xml
-        retention-days: 1 # Artifact will be available only for 5 days.
+        retention-days: 1 
+
   sonar-scan:    
-    name: Sonar scan
+    name: SonarCloud Scan
     runs-on: ubuntu-latest
     needs: build
     steps:
@@ -63,7 +86,7 @@ jobs:
         with:
           ref: ${{ github.HEAD_REF }}
           fetch-depth: 0       
-      - name: Check compiler version
+      - name: Check compiler version, for debugging
         run: |
           g++ --version
           cmake --version
@@ -73,19 +96,22 @@ jobs:
       - name: Set up Python 3.8 for gcovr
         uses: actions/setup-python@v5
         with: 
-          python-version: 3.8
-      - name: install gcovr 5.0
+          python-version: 3.12
+      # Gcovr provides a utility for managing the use of the GNU gcov utility and generating 
+      # summarized code coverage results. This command is inspired by the Python coverage.py 
+      # package, which provides a similar utility for Python.
+      # https://pypi.org/project/gcovr/
+      - name: Install gcovr
         run: |
-          pip install gcovr==5.0 # 5.1 is not supported by sonarcloud
+          pip install gcovr==8.3
+      # SonarQube Server and Cloud (formerly SonarQube and SonarCloud) is a widely used static 
+      # analysis solution for continuous code quality and security inspection.
+      # This action now supports and is the official entrypoint for scanning C++ projects via GitHub actions.
+      # https://github.com/SonarSource/sonarqube-scan-action
       - name: Install Build Wrapper
-        uses: SonarSource/sonarqube-scan-action/install-build-wrapper@v4.2.1
-      # - name: Install sonar-scanner and build-wrapper
-      #   uses: SonarSource/sonarcloud-github-c-cpp@v3   
+        uses: SonarSource/sonarqube-scan-action/install-build-wrapper@v4.2.1 
       - name: Download all workflow run artifacts
         uses: actions/download-artifact@v4
-      - name: Unpack Artifact  
-        run: >
-          ls -l ./
       - name: Configure CMake
         run: cmake -S ${{github.workspace}} -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
       - name: Run build-wrapper
@@ -97,15 +123,5 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN  }} 
         with:
-          # Consult https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/scanners/sonarscanner/ for more information and options
           args: >
-            --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json" \
-      #       -Dsonar.coverageReportPaths=artifact/sonarqube-generic-coverage.xml
-      # - name: Run sonar-scanner
-      #   env:
-      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      #     SONAR_TOKEN: ${{ secrets.SONAR_TOKEN  }} 
-      #   run: |
-      #     sonar-scanner \
-      #     --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json" \
-      #     -Dsonar.coverageReportPaths=artifact/sonarqube-generic-coverage.xml
\ No newline at end of file
+            --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json" \
\ No newline at end of file

From 915a37181c66dcf6b8afaadfec8ed2576f6f3cb2 Mon Sep 17 00:00:00 2001
From: Ryan <16667079+mccaffers@users.noreply.github.com>
Date: Sun, 2 Feb 2025 13:40:24 +0000
Subject: [PATCH 6/6] Refactoring the workflow file

---
 .github/workflows/brew.sh        | 17 +++++++++++++++--
 .github/workflows/sonarcloud.yml | 13 ++++++-------
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/brew.sh b/.github/workflows/brew.sh
index a4289ed..5e03be3 100644
--- a/.github/workflows/brew.sh
+++ b/.github/workflows/brew.sh
@@ -1,2 +1,15 @@
-brew install postgresql
-brew install pkg-config 
\ No newline at end of file
+#!/bin/bash
+
+# Check if a package is already installed via Homebrew, then skip
+check_and_install() {
+    if ! brew list $1 &>/dev/null; then
+        echo "Installing $1..."
+        brew install $1
+    else
+        echo "$1 is already installed"
+    fi
+}
+
+# Install packages if they don't exist
+check_and_install postgresql
+check_and_install pkg-config
\ No newline at end of file
diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml
index b26e7c4..b84ab97 100644
--- a/.github/workflows/sonarcloud.yml
+++ b/.github/workflows/sonarcloud.yml
@@ -1,7 +1,7 @@
-# Workflow for building and testing the project
+# Backtesting C++ Workflow
+# To build, test and perform SonarCloud analysis
 name: Build
 
-# Define when the workflow should run
 on:
   push:
     branches:
@@ -9,7 +9,6 @@ on:
   pull_request:
     types: 
       - opened      # When PR is first created
-      - edited      # When PR description/title is edited
       - synchronize # When new commits are pushed to the PR
       - reopened    # When PR is reopened after being closed
 
@@ -37,8 +36,8 @@ jobs:
     - name: Install dependencies
       run: bash ./.github/workflows/brew.sh
 
-    # Step 4: Build project libraries
-    - name: Build libraries
+    # Step 4: Build project external libraries
+    - name: Build C++ Libraries
       run: bash ./.github/workflows/build.sh
 
     # Step 5: Configure Xcode version
@@ -90,10 +89,10 @@ jobs:
         run: |
           g++ --version
           cmake --version
-      - name: Build libraries
+      - name: Build C++ Libraries
         run: >
             bash ./.github/workflows/build.sh
-      - name: Set up Python 3.8 for gcovr
+      - name: Install Python 3.12 for gcovr
         uses: actions/setup-python@v5
         with: 
           python-version: 3.12