Added package-pack comments

Author: michalChrobot

.yamato/package-pack.yml

@@ -1,9 +1,28 @@
-{% metadata_file .yamato/project.metafile %}
+{% metadata_file .yamato/project.metafile %} # All configuration that is used to create different configurations (used in for loops) is taken from this file.
 ---
 
-# Packs Netcode for GameObjects together with performing initial checks. 
-# For this job no specific platform support and no running Unity instance is required so small agent (as per project.metafile definition) could be used to save resources and speed up the process.
-# If everyone adheres to this rule it can create bottlenecks (since everyone would use this machine) so we decided to pack with the same platform as the given job runs on
+# DESCRIPTION--------------------------------------------------------------------------
+  # This job is responsible for packing a specific package. It generates package artifacts (.tgz) required for testing and publishing, ensuring all dependencies are properly bundled and validated before any test execution.
+  # The job itself doesn't test anything specific but rather it prepares project packages that will be consumed by other pipeline jobs.
+  # The job performs additional validation by using Package Verification Pipeline (PVP). It includes x-ray validation for quick package structure verification
+  # Because of that validation we can detect errors at the early stage of testing so not to waste CI resources
+
+# CONFIGURATION STRUCTURE--------------------------------------------------------------
+  # Jobs are generated using nested loops through:
+    # 1. For all desktop platforms (Windows, Ubuntu, macOS)
+
+# TECHNICAL CONSIDERATIONS---------------------------------------------------------------
+  # Job does not require Unity Editor in order to perform packing.
+  # Job uses PVP x-ray for lightweight validation
+  # Job generates both packages artifacts and pvp-results file.
+  # In theory, we could just use one platform for packing projects (for example ubuntu) but in order to reduce confusion we are using same platform as the job utilizing project pack as dependency.
+
+# QUALITY CONSIDERATIONS--------------------------------------------------------------------
+  # To see where this job is included (in trigger job definitions) look into _triggers.yml file
+  # TODO: we should aim to replace target PVP profile from supported to gold
+
+#------------------------------------------------------------------------------------
+  
 {% for platform in test_platforms.desktop -%}
 package_pack_-_ngo_{{ platform.name }}:
   name: Package Pack (and x-ray) - NGO [{{ platform.name }}]