chore(ci): Update workflow names + add comments (#2337)

* Update workflow names + add comments

* Add npmjs registry links in publish-latest comment

* Add info about "run-test" label

Author: wlee221

.github/workflows/publish-latest.yml

@@ -1,4 +1,14 @@
-name: Publish to latest
+# Description: this workflow publishes UI packages to `latest` tag on NPM.
+#
+# Triggered by: whenever "Version Packages" is merged
+
+# If successful, we will publish all updated UI packages to
+#   - https://www.npmjs.com/package/@aws-amplify/ui
+#   - https://www.npmjs.com/package/@aws-amplify/ui-react
+#   - https://www.npmjs.com/package/@aws-amplify/ui-vue
+#   - https://www.npmjs.com/package/@aws-amplify/ui-angular
+
+name: Test and Publish / latest
 
 on:
   push:
@@ -21,6 +31,13 @@ jobs:
       - name: Check if repo has unconsumed changesets
         id: has-changesets
         uses: ./.github/actions/has-changesets
+      # Note: if there are no changesets, that means that either
+      #         (1) "Version Packages" PR was just merged, or
+      #         (2) no commits with changesets have been merged after packages were last published.
+      #
+      #       In either way, we'll attempt to publish the packages. In case of (1), publish will succeed. In
+      #       case of (2), `@changesets/action` will know that UI packages have already published and will
+      #       skip publish.
 
   build-test:
     runs-on: ubuntu-latest

.github/workflows/test-deploy-main.yml .github/workflows/publish-next.yml.github/workflows/test-deploy-main.yml renamed to .github/workflows/publish-next.yml

@@ -1,6 +1,9 @@
-# This workflow will run unit, e2e, and docs tests on commits to main.
+# Description: This workflow runs unit + e2e tests, then publishes UI packages
+#              to `@next` NPM tag.
+#
+# Triggered by: merge to `main`
 
-name: Test and Publish / main
+name: Test and Publish / next
 
 concurrency:
   group: e2e-${{ github.sha }}

.github/workflows/test-deploy-studio.yml .github/workflows/publish-studio.yml.github/workflows/test-deploy-studio.yml renamed to .github/workflows/publish-studio.yml

@@ -1,4 +1,7 @@
-# This workflow will run unit, e2e, and docs tests on commits to main.
+# Description: This workflow runs unit + e2e tests, then publishes UI packages
+#              to `@studio` NPM tag.
+#
+# Triggered by: merge to `studio-release` branch
 
 name: Test and Publish / studio
 

.github/workflows/reusable-e2e.yml

@@ -1,3 +1,7 @@
+# Description: this is a reusable workflow that runs unit and e2e tests.
+#
+# See `./test-prs.yml` to see an example usage.
+
 on:
   workflow_call:
     inputs:

.github/workflows/run-and-test-builds.yml

@@ -1,3 +1,8 @@
+# Description: this workflow runs build and simple runtime tests on supported
+#              frameworks and their build systems.
+#
+# Triggered by: it runs every 15 minutes.
+
 name: Run and Test Builds
 
 on:

.github/workflows/test-prs.yml

@@ -1,4 +1,9 @@
-# This workflow will run unit, e2e, and docs tests on PRs targeted against main, ui-svelte/main, ui-geo/main, and ui-react@v2 branches.
+# Description: This workflow runs unit + e2e tests on PRs targeting `main` and
+#              other protected branches listed below.
+#
+# Triggered by:
+#   (1) Internal PRs: contirubutor pushes a commit to PRs targeting protected branches.
+#   (2) Fork PRs: maintainer adds "run-test" label to PRs targeting protected branches.
 
 name: Test / PRs
 

.github/workflows/version-packages.yml

@@ -1,3 +1,8 @@
+# Description: this workflow creates or updates the "Version Packages" PR.
+#
+# Triggered by: whenever a commit is merged onto main and there are
+#               new changesets to consume.
+
 name: Version Packages
 
 on: