[DOC] Clarify description of manual label push workflow (#14)

* [DOC] Add context comments

Explain purpose of job and odd choices

* Clarify job name

.github/workflows/manual_wf.yml → .github/workflows/manual_label_population_to_repos.yml

@@ -1,3 +1,23 @@
+# The purpose of this workflow is to take all labels
+# in this repository (neurobagel/planning) and push them
+# to all repositories owned by the neurobagel organization.
+# 
+# This workflow complements the automatic label syncing workflow
+# label_sync.yml that is triggered when a label is created or edited.
+# The present workflow is probably most useful when we create a new
+# repository and then want to make sure that it immediately receives
+# all of our standard labels.
+#
+# The workflow has the following jobs in this order:
+# 1. get_labels: Find all labels in the planning repo and store them 
+#    in the output variable "labels" of the job.
+# 2. sync_labels: Create a separate job for each label and then within
+#    that job conduct the following steps:
+#    2.1. read_label: Read the description and color of the label via a
+#       GitHub GRAPHQL API call and store them as environment variables.
+#    2.2. sync_label: Find all repositories owned by neurobagel and iterate
+#       over them, pushing the previously stored label information to each one.
+
 name: Manual Sync of labels
 on:
   workflow_dispatch
@@ -25,6 +45,10 @@ jobs:
     env:
       GH_TOKEN: ${{ secrets.LAB_PAT }}
     strategy:
+      # Note: we cannot make a matrix for the label AND repo at once,
+      # because the total number of jobs will exceed the maximum allowed by GitHub.
+      # Therefore we create one job per label here and then iterate over the repositories
+      # inside of the job directly.
       matrix:
         label: ${{fromJSON(needs.get_labels.outputs.labels)}}
     steps:
@@ -57,6 +81,15 @@ jobs:
             echo "description=${label_description}" >> $GITHUB_OUTPUT
             echo "color=${label_color}" >> $GITHUB_OUTPUT
 
+      # Note that we have to iterate over the repositories inside of the job rather than as
+      # part of the job matrix because GH only allows 255 matrix jobs at a time.
+      # The major downside is that if any of the repositories fail, the entire step will fail
+      # and none of the subsequent repos will be synced.
+      # 
+      # Github actions run with set -e, i.e. they immediately fail if any step has a non-zero exit status.
+      # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#exit-codes-and-error-action-preference
+      # Conveniently, grep has by default a non-zero exit status if no match is found, so we have to escape
+      # that the entire step to fail and all subsequent repositories to not be synced.
       - name: sync label
         env:
           MAX_REPO: 100