refactoring the workflow, bumping python and gcovr

Author: mccaffers

.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/[email protected]
-      # - name: Install sonar-scanner and build-wrapper
-      #   uses: SonarSource/sonarcloud-github-c-cpp@v3   
+        uses: SonarSource/sonarqube-scan-action/[email protected] 
       - 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
+            --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json" \