Second comment pass

Author: michalChrobot

.yamato/_run-all.yml

@@ -2,8 +2,16 @@
 ---
 
 # DESCRIPTION--------------------------------------------------------------------------
-  # Those jobs group together related test executions
-  # Enables efficient test execution for different validation scenarios
+  # Those jobs group together related test as dependencies to allow to easily manage running a given set of tests.
+  # This enables efficient test execution for different validation scenarios
+
+# CONFIGURATION STRUCTURE--------------------------------------------------------------
+  # It may seem that there is only 1 job defined, but we are using "for" loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
+  # Jobs are generated using nested loops through:
+  
+  # It's important to ensure that all generated in such way dependencies exist (this can be verified in Yamato)
+  # In theory, we could manually write jobs for every configuration. However, this approach would be more error-prone, especially when modifications or fixes are needed, as it would require keeping track of all configurations.
+  # The downside of our current approach is that it can sometimes impact readability due to the use of nested if and for statements.
 
 #-----------------------------------------------------------------------------------
 

.yamato/_triggers.yml

@@ -2,30 +2,37 @@
 ---
 
 # DESCRIPTION--------------------------------------------------------------------------
-# Defines three main CI trigger patterns:
-  # 1. Pull Request Validation: Basic validation for PR changes
-  # 2. Nightly Development: Comprehensive testing on trunk
-  # 3. Weekly Full Validation: Complete testing across all editor versions
-# Each pattern represents different balance between validation depth, execution time and CI resource usage
+  # This configuration defines three main CI trigger patterns:
+    # 1. Pull Request Validation: Validation performed on PR basis
+    # 2. Nightly Development: Test set run nightly (validates most important test cases)
+    # 3. Weekly Full Validation: Test set run weekly (validates all test cases to prevent any suprises)
+  # Each pattern represents different balance between validation depth, execution time and CI resource usage
 
 # TRIGGER PATTERNS-------------------------------------------------------------------
   # Pull Request:
+    # This test validaes Standards, Package tests, Project tests and Desktop standalone tests to ensure that main platforms are covered
     # Triggers on PRs to develop, develop-2.0.0, and release branches
     # Focuses on critical validation paths that we should validate before merging PRs
     # Cancels previous runs on new commits
     # Excludes draft PRs
 
   # Nightly:
+    # This test validaes same subset as pull_request_trigger with addition of mobile/console tests and webgl builds
     # Runs daily on develop-2.0.0 (local configuration)
     # Includes all test types but only on trunk. TODO: Add validation for minimum supported editor in nightly
     # Adds platform-specific and APV validation
 
   # Weekly:
-    # Most comprehensive validation
+  # This test validaes same subset as develop_nightly but runs per all supported editors as well as executes code coverage test and runs project standards per project
     # Runs across all supported editor versions
     # Includes code coverage analysis
     # Validates all projects and standards
 
+# CONFIGURATION STRUCTURE--------------------------------------------------------------
+  # Jobs configurations are generated by ensuring that all dependencies are successful.
+  # The dependencies are taken from _run-all.yml file where we can gather multiple tests into proper sets
+
+
 #-----------------------------------------------------------------------------------
 
 # Run all relevant tasks when a pull request targeting the develop or release branch is created or updated.

.yamato/code-coverage.yml

@@ -2,15 +2,15 @@
 ---
 
 # DESCRIPTION--------------------------------------------------------------------------
-  # This job executes package tests with code coverage analysis enabled for the NGO (Netcode for GameObjects) package
+  # This job is responsible for executing package tests with code coverage analysis enabled.
   # Coverage analysis provides insights into:
     # Test coverage metrics for NGO assemblies
     # Line and branch coverage statistics
     # Generated HTML reports for coverage visualization
     # Additional metrics for coverage analysis
 
 # CONFIGURATION STRUCTURE--------------------------------------------------------------
-  # It may seem that there is only 1 job defined, but we are using for loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
+  # It may seem that there is only 1 job defined, but we are using "for" loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
   # Jobs are generated using nested loops through:
     # 1. For default platform only (Ubuntu) since coverage would not vary between platforms (no need for checks on more platforms)
     # 2. For default editor version (trunk) since coverage would not vary between editors (no need for checks on more editors)
@@ -20,13 +20,14 @@
 
   # The jobs name being generated would be for example "Code Coverage - NGO [testproject, 6000.0]" (name visible in Yamato) or "code_coverage_testproject_6000.0" (job name when querying for it)
 
-#TECHNICAL CONSTRAINTS---------------------------------------------------------------
+#TECHNICAL CONSIDERATIONS---------------------------------------------------------------
+  # In theory this job also runs package tests, but we don't want to use it as default since is heavier (because of added coverage analysis) and coverage is not changing that often
   # Requires Unity Editor installation
-  # Uses UnifiedTestRunner (UTR) for test execution
-  # Depends on successful package pack job completion
   # Burst compilation is disabled to ensure accurate coverage measurement
+  # In order to properly use -coverage-results-path parameter we need to start it with $PWD (which means the absolute path). Otherwise coverage results will not be visible
 
-# QUALITY THOUGHTS--------------------------------------------------------------------
+# QUALITY CONSIDERATIONS--------------------------------------------------------------------
+  # TODO: somewhere in 2025 we will be able to upload resuls to CodeCov from public repos
   # To see where this job is included (in trigger job definitions) look into _triggers.yml file
 
 

.yamato/console-standalone-test.yml

@@ -2,23 +2,30 @@
 ---
 
 # DESCRIPTION--------------------------------------------------------------------------
-  # This file contains Console platform test validation for NGO package consisting of two phases:
-    # 1. Build Phase: Creates standalone players for console platforms
-    # 2. Run Phase: Executes runtime tests on actual console devices
-  # Those phases need to be separated (in contrast to for example desktop tests)
+  # This job is responsible for Console platform test validation.
+  # Those tests cover both PlayMode and EditMode tests from package test assemblies.
 
 # CONFIGURATION STRUCTURE--------------------------------------------------------------
-  # It may seem that there is only 1 job defined, but we are using for loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
+  # It may seem that there is only 1 job defined, but we are using "for" loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
   # Jobs are generated using nested loops (separate build phase and run phase). Worth noting that run phase uses the build as dependency:
-    # 1. For all console platform (Switch, ps4, ps5, xbox360, xboxOne) defined in test_platforms.console_ (in project.metafile)
-    # 2. For all supported Unity Editor versions (for NGOv2.X this means 6000.0+ editors defined in project.metafile)
-  # 3. For default project which serves as context
+    # 1. For all console platform (Switch, ps4, ps5, xbox360, xboxOne)
+    # 2. For all supported Unity Editor versions (for NGOv2.X this means 6000.0+ editors)
+  ` # 3. For the default project.
   
   # In theory, we could manually write jobs for every configuration. However, this approach would be more error-prone, especially when modifications or fixes are needed, as it would require keeping track of all configurations.
   # The downside of our current approach is that it can sometimes impact readability due to the use of nested if and for statements.
   
   # The jobs name being generated would be for example "Build testproject - [win, 6000.0, il2cpp]" (name visible in Yamato) or "console_standalone_build_testproject_win_6000.0" (job name when querying for it)   
   
+# TECHNICAL CONSIDERATIONS---------------------------------------------------------------
+  # For console devices a split is required into two phases:
+    # 1. Build Phase: Creates standalone players for console platforms
+    # 2. Run Phase: Executes runtime tests on actual console devices
+  # The Run phase uses build job as dependency
+  
+  # Note: More of a Unity specific but test assemblies need to be included in the build phase command
+  # Note: All builds can be made on x64 machines since those are compatible with ARM64 target devices
+  
 # PLATFORM SPECIFICS-----------------------------------------------------------------
   # Common Requirements:
     # All consoles require IL2CPP scripting backend
@@ -28,11 +35,9 @@
     # Switch: ARM64 architecture only
     # Other Consoles: x64 architecture
     # Each console requires specific SDK paths and tools
-
-  # Note: All builds can be made on x64 machines since those are compatible with ARM64 target devices
-  # Note: More of a Unity specific but test assemblies need to be included in the build phase command
   
 # QUALITY THOUGHTS--------------------------------------------------------------------
+  # TODO: consider adding all projects that have tests
   # To see where this job is included (in trigger job definitions) look into _triggers.yml file
 
   

.yamato/desktop-standalone-tests.yml

@@ -2,25 +2,33 @@
 ---
 
 # DESCRIPTION--------------------------------------------------------------------------
-  # This file contains Desktop platform test validation for NGO package consisting of two phases:
-    # 1. Build Phase: Creates standalone players for desktop platforms
-    # 2. Run Phase: Executes runtime tests on actual desktop devices
-  # For desktop devices the phase separation is not necessary, but we did it for consistency with other standalone tests configurations
+  # This job is responsible for Desktop platform test validation.
+  # Those tests cover both PlayMode and EditMode tests from package test assemblies.
 
 # CONFIGURATION STRUCTURE--------------------------------------------------------------
-  # It may seem that there is only 1 job defined, but we are using for loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
+  # It may seem that there is only 1 job defined, but we are using "for" loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
   # Jobs are generated using nested loops (separate build phase and run phase). Worth noting that run phase uses the build as dependency:
-    # 1. For all desktop platform (Windows, macOS, Ubuntu) defined in test_platforms.desktop_ (in project.metafile)
-    # 2. For all supported Unity Editor versions (for NGOv2.X this means 6000.0+ editors defined in project.metafile)
-    # 3. For default project which serves as context
-    # 4. For all scripting backends
+    # 1. For all desktop platform (Windows, macOS, Ubuntu)
+    # 2. For all supported Unity Editor versions (for NGOv2.X this means 6000.0+ editors)
+    # 3. For the default project.
+    # 4. For all scripting backends (mono, il2cpp)
 
   # In theory, we could manually write jobs for every configuration. However, this approach would be more error-prone, especially when modifications or fixes are needed, as it would require keeping track of all configurations.
   # The downside of our current approach is that it can sometimes impact readability due to the use of nested if and for statements.
 
   # The jobs name being generated would be for example "Standalone Build - NGO testproject - [win, mono, 6000.0]" (name visible in Yamato) or "desktop_standalone_build_testproject_win_mono_6000.0" (job name when querying for it)   
 
+# TECHNICAL CONSIDERATIONS---------------------------------------------------------------
+  # For desktop devices a split is into two phases is not required but we use it for consistency with setup of others standalone platforms:
+    # 1. Build Phase: Creates standalone players for desktop platforms
+    # 2. Run Phase: Executes runtime tests on actual desktop devices
+  # The Run phase uses build job as dependency
+  
+  # Note: More of a Unity specific but test assemblies need to be included in the build phase command
+  # Note: All builds can be made on x64 machines since those are compatible with ARM64 target devices
+
 # QUALITY THOUGHTS--------------------------------------------------------------------
+  # TODO: consider adding all projects that have tests
   # To see where this job is included (in trigger job definitions) look into _triggers.yml file
 
 #-----------------------------------------------------------------------------------

.yamato/mobile-standalone-test.yml

@@ -2,24 +2,30 @@
 ---
 
 # DESCRIPTION--------------------------------------------------------------------------
-  # This file contains Mobile platform test validation for NGO package consisting of two phases:
-    # 1. Build Phase: Creates standalone players for mobile platforms
-    # 2. Run Phase: Executes runtime tests on actual mobile devices
-  # Those phases need to be separated (in contrast to for example desktop tests)
+  # This job is responsible for Mobile platform test validation.
+  # Those tests cover both PlayMode and EditMode tests from package test assemblies.
 
 # CONFIGURATION STRUCTURE--------------------------------------------------------------
-  # It may seem that there is only 1 job defined, but we are using for loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
-  # Jobs are generated using nested loops (separate build phase and run phase). Worth noting that run phase uses the build as dependency:
-    # 1. For all mobile platform (Android, iOS) defined in test_platforms.mobile_ (in project.metafile)
-    # 2. For all supported Unity Editor versions (for NGOv2.X this means 6000.0+ editors defined in project.metafile)
-    # 3. For default project which serves as context
+  # It may seem that there is only 1 job defined, but we are using "for" loops based on .yamato/project.metafile configuration. Yamato "compiles" this code in order to generate jobs with multiple given configurations
+  # Jobs are generated using nested loops through:
+    # 1. For all mobile platform (Android, iOS)
+    # 2. For all supported Unity Editor versions (for NGOv2.X this means 6000.0+ editors)
+    # 3. For the default project.
 
   # In theory, we could manually write jobs for every configuration. However, this approach would be more error-prone, especially when modifications or fixes are needed, as it would require keeping track of all configurations.
   # The downside of our current approach is that it can sometimes impact readability due to the use of nested if and for statements.
 
   # The jobs name being generated would be for example "Build testproject - [win, 6000.0, il2cpp]" (name visible in Yamato) or "build_testproject_win_6000.0" (job name when querying for it)   
 
-# PLATFORM SPECIFICS-----------------------------------------------------------------
+# TECHNICAL CONSIDERATIONS---------------------------------------------------------------
+  # For mobile devices a split is required into two phases:
+    # 1. Build Phase: Creates standalone players for mobile platforms
+    # 2. Run Phase: Executes runtime tests on actual mobile devices
+  # The Run phase uses build job as dependency
+  # Note: More of a Unity specific but test assemblies need to be included in the build phase command
+  # Note: All builds can be made on x64 machines since those are compatible with ARM64 target devices
+  
+# PLATFORM SPECIFICS--------------------------------------------------------------------
   # iOS Requirements:
     # Must use IL2CPP scripting backend
     # Only supports ARM64 architecture
@@ -29,11 +35,9 @@
       # Uses IL2CPP scripting backend (recommended over Mono)
       # Supports both ARM64 and ARMv7 architectures
       # Can be build on any desktop platform
-
-  # Note: All builds can be made on x64 machines since those are compatible with ARM64 target devices
-  # Note: More of a Unity specific but test assemblies need to be included in the build phase command
 
-# QUALITY THOUGHTS--------------------------------------------------------------------
+# QUALITY CONSIDERATIONS--------------------------------------------------------------------
+  # TODO: consider adding all projects that have tests
   # To see where this job is included (in trigger job definitions) look into _triggers.yml file
 
 
@@ -49,7 +53,6 @@ mobile_standalone_build_{{ project.name }}_{{ platform.name }}_{{ editor }}:
       flavor: {{ platform.flavor }}
   commands:
     - unity-downloader-cli -u {{ editor }} -c Editor -c il2cpp {% if platform.base == "mac" %} -c ios {% else %} -c android {% endif %}
-    
     - UnifiedTestRunner --suite=playmode --platform={{ platform.standalone }} --testproject={{ project.path }} --architecture={{ platform.architecture }} --scripting-backend=il2cpp --editor-location=.Editor --artifacts-path=artifacts --testfilter="Unity.Netcode.RuntimeTests.*" --player-save-path=build/players --extra-editor-arg=-batchmode --extra-editor-arg=-nographics --reruncount=1 --clean-library-on-rerun --build-only --timeout=1800
   artifacts:
     players:
@@ -77,7 +80,7 @@ mobile_standalone_test_{{ project.name }}_tests_{{ platform.name }}_{{ editor }}
     model: {{ platform.model }}
 {% endif %}
   commands:
-    # Installing editor. We still need the editor to run tests on standalone build
+    # Installing editor. We still need the editor to run tests on standalone build and for that the Editor is required
     - unity-downloader-cli -u {{ editor }} -c Editor -c il2cpp {% if platform.base == "mac" %} -c ios {% else %} -c android {% endif %}
 
 {% if platform.standalone == "Android" %}