.sync/workflows/codeql: Add more inline documentation

Updates and adds some additional comments to the CodeQL workflow
files to give better context.

Signed-off-by: Michael Kubacki <[email protected]>

.sync/workflows/leaf/codeql-platform.yml

@@ -3,11 +3,16 @@
 # Any platform that supports the `--codeql` parameter will be built and the
 # results will be uploaded to GitHub Code Scanning.
 #
+# Note: Important: This file only works with "platform" builds. "CI" builds are
+# supported with the codeql.yml file.
+#
 # Note: This workflow only supports Windows as CodeQL CLI has confirmed issues running
 # against edk2-style codebases on Linux (only tested on Ubuntu). Therefore, this
 # workflow is written only for Windows but could easily be adapted to run on Linux
 # in the future if needed (e.g. swap out "windows" with agent OS var value, etc.)
 #
+# For details about the Linux issue see: https://github.com/github/codeql-action/issues/1338
+#
 # NOTE: This file is automatically synchronized from Mu DevOps. Update the original file there
 # instead of the file in this repo.
 #
@@ -323,7 +328,14 @@ jobs:
  import sys
  from pathlib import Path
 
- # Find the plugin directory that contains the CodeQL plugin
+ #
+ # Find the plugin directory that contains the CodeQL plugin.
+ #
+ # Prior to Mu Basecore 202311, the CodeQL plugin was located in .pytool. After it
+ # is located in BaseTools. First check BaseTools, but consider .pytool as a backup
+ # for backward compatibility. The .pytool backup can be removed when no longer needed
+ # for supported branches.
+ #
  plugin_dir = list(Path(os.environ['GITHUB_WORKSPACE']).rglob('BaseTools/Plugin/CodeQL'))
  if not plugin_dir:
  plugin_dir = list(Path(os.environ['GITHUB_WORKSPACE']).rglob('.pytool/Plugin/CodeQL'))
@@ -407,7 +419,14 @@ jobs:
  import shutil
  from pathlib import Path
 
- # Only these two plugins are needed for CodeQL
+ # Only these two plugins are needed for CodeQL.
+ #
+ # CodeQL build time is reduced by removing other plugins that are not needed for the CodeQL
+ # build in the .pytool directory. The CompilerPlugin is required to compile code for CodeQL
+ # to extract results from and the CodeQL plugin is necessary to to analyze the results and
+ # build the CodeQL database from them. The CodeQL plugin should be in BaseTools moving forward
+ # but still might be in .pytool in older branches so it is kept here as an exception.
+ #
  plugins_to_keep = ['CodeQL', 'CompilerPlugin']
 
  plugin_dir = Path(os.environ['PYTOOL_PLUGIN_DIR']).absolute()

.sync/workflows/leaf/codeql.yml

@@ -2,13 +2,15 @@
 #
 # Results are uploaded to GitHub Code Scanning.
 #
-# Note: Important: This file currently only works with "CI" builds. "Platform" builds can
-#  be supported without much effort but that will be done in the future.
+# Note: Important: This file only works with "CI" builds. "Platform" builds are
+# supported with the codeql-platform.yml file.
 #
 # Note: This workflow only supports Windows as CodeQL CLI has confirmed issues running
 # against edk2-style codebases on Linux (only tested on Ubuntu). Therefore, this
 # workflow is written only for Windows but could easily be adapted to run on Linux
-# in the future if needed (e.g. swap out "windows" with agent OS var value, etc.)
+# in the future if needed (e.g. swap out "windows" with agent OS var value, etc.).
+#
+# For details about the Linux issue see: https://github.com/github/codeql-action/issues/1338
 #
 # NOTE: This file is automatically synchronized from Mu DevOps. Update the original file there
 # instead of the file in this repo.
@@ -270,7 +272,14 @@ jobs:
  import sys
  from pathlib import Path
 
- # Find the plugin directory that contains the CodeQL plugin
+ #
+ # Find the plugin directory that contains the CodeQL plugin.
+ #
+ # Prior to Mu Basecore 202311, the CodeQL plugin was located in .pytool. After it
+ # is located in BaseTools. First check BaseTools, but consider .pytool as a backup
+ # for backward compatibility. The .pytool backup can be removed when no longer needed
+ # for supported branches.
+ #
  plugin_dir = list(Path(os.environ['GITHUB_WORKSPACE']).rglob('BaseTools/Plugin/CodeQL'))
  if not plugin_dir:
  plugin_dir = list(Path(os.environ['GITHUB_WORKSPACE']).rglob('.pytool/Plugin/CodeQL'))
@@ -352,7 +361,14 @@ jobs:
  import shutil
  from pathlib import Path
 
- # Only these two plugins are needed for CodeQL
+ # Only these two plugins are needed for CodeQL.
+ #
+ # CodeQL build time is reduced by removing other plugins that are not needed for the CodeQL
+ # build in the .pytool directory. The CompilerPlugin is required to compile code for CodeQL
+ # to extract results from and the CodeQL plugin is necessary to to analyze the results and
+ # build the CodeQL database from them. The CodeQL plugin should be in BaseTools moving forward
+ # but still might be in .pytool in older branches so it is kept here as an exception.
+ #
  plugins_to_keep = ['CodeQL', 'CompilerPlugin']
 
  plugin_dir = Path(os.environ['PYTOOL_PLUGIN_DIR']).absolute()