Add annotations to workflow examples for automating builds and tests …

…(#39064)

Co-authored-by: Sarah Edwards <skedwards88@github.com>

content/actions/automating-builds-and-tests/building-and-testing-java-with-ant.md

@@ -15,8 +15,9 @@ topics:
   - Java
   - Ant
 shortTitle: Build & test Java & Ant
+layout: inline
 ---
- 
+
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
 ## Introduction
@@ -41,42 +42,38 @@ We recommend that you have a basic understanding of Java and the Ant framework.
 
 ## Using the Ant starter workflow
 
-{% data variables.product.prodname_dotcom %} provides an Ant starter workflow that will work for most Ant-based Java projects. For more information, see the [Ant starter workflow](https://github.com/actions/starter-workflows/blob/main/ci/ant.yml).
+{% data variables.product.prodname_dotcom %} provides an Ant starter workflow that will work for most Ant-based Java projects. For more information, see the [Ant starter workflow](https://github.com/actions/starter-workflows/blob/main/ci/ant.yml). {% data reusables.actions.workflows.starter-workflows %}
 
 To get started quickly, you can choose the preconfigured Ant starter workflow when you create a new workflow. For more information, see the "[AUTOTITLE](/actions/quickstart)."
 
 You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository.
 
-```yaml copy
+```yaml annotate copy
+# {% data reusables.actions.workflows.workflow-syntax-name %}
 name: Java CI
 
+#
 on: [push]
-
+#
 jobs:
   build:
+    {% data reusables.actions.example-github-runner-comment %}
     runs-on: ubuntu-latest
-
+#
     steps:
+      {% data reusables.actions.workflows.workflow-checkout-step-explainer %}
       - uses: {% data reusables.actions.action-checkout %}
+      {% data reusables.actions.workflows.setup-java-step-explainer %}
       - name: Set up JDK 17
         uses: {% data reusables.actions.action-setup-java %}
         with:
           java-version: '17'
           distribution: 'temurin'
+      # This step runs the default target in your `build.xml` file in non-interactive mode.
       - name: Build with Ant
         run: ant -noinput -buildfile build.xml
 ```
 
-This workflow performs the following steps:
-
-1. The `checkout` step downloads a copy of your repository on the runner.
-1. The `setup-java` step configures the Eclipse Temurin (Java) 17 JDK by Eclipse Adoptium.
-1. The "Build with Ant" step runs the default target in your `build.xml` in non-interactive mode.
-
-The default starter workflows are excellent starting points when creating your build and test workflow, and you can customize the starter workflow to suit your project’s needs.
-
-{% data reusables.actions.example-github-runner %}
-
 {% data reusables.actions.java-jvm-architecture %}
 
 ## Building and testing your code
@@ -111,7 +108,7 @@ steps:
     with:
       java-version: '17'
       distribution: 'temurin'
-  
+
   - run: ant -noinput -buildfile build.xml
   - uses: {% data reusables.actions.action-upload-artifact %}
     with:

content/actions/automating-builds-and-tests/building-and-testing-java-with-gradle.md

@@ -15,8 +15,9 @@ topics:
   - Java
   - Gradle
 shortTitle: Build & test Java & Gradle
+layout: inline
 ---
- 
+
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
 ## Introduction
@@ -41,51 +42,53 @@ We recommend that you have a basic understanding of Java and the Gradle framewor
 
 ## Using the Gradle starter workflow
 
-{% data variables.product.prodname_dotcom %} provides a Gradle starter workflow that will work for most Gradle-based Java projects. For more information, see the [Gradle starter workflow](https://github.com/actions/starter-workflows/blob/main/ci/gradle.yml).
+{% data variables.product.prodname_dotcom %} provides a Gradle starter workflow that will work for most Gradle-based Java projects. For more information, see the [Gradle starter workflow](https://github.com/actions/starter-workflows/blob/main/ci/gradle.yml). {% data reusables.actions.workflows.starter-workflows %}
 
 To get started quickly, you can choose the preconfigured Gradle starter workflow when you create a new workflow. For more information, see the "[AUTOTITLE](/actions/quickstart)."
 
 You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository.
 
-```yaml copy
-{% data reusables.actions.actions-not-certified-by-github-comment %}
+{% note %}
+
+**Notes:**
 
-{% data reusables.actions.actions-use-sha-pinning-comment %}
+- {% data reusables.actions.actions-not-certified-by-github %}
+- {% data reusables.actions.actions-use-sha-pinning %}
 
+{% endnote %}
+
+```yaml annotate copy
+# {% data reusables.actions.workflows.workflow-syntax-name %}
 name: Java CI
 
+#
 on: [push]
-
+#
 jobs:
   build:
-    runs-on: ubuntu-latest
 
+    {% data reusables.actions.example-github-runner-comment %}
+    runs-on: ubuntu-latest
+#
     steps:
+      {% data reusables.actions.workflows.workflow-checkout-step-explainer %}
       - uses: {% data reusables.actions.action-checkout %}
+      {% data reusables.actions.workflows.setup-java-step-explainer %}
       - name: Set up JDK 17
         uses: {% data reusables.actions.action-setup-java %}
         with:
           java-version: '17'
           distribution: 'temurin'
+      # The "Validate Gradle wrapper" step validates the checksums of Gradle Wrapper JAR files present in the source tree.
       - name: Validate Gradle wrapper
         uses: gradle/wrapper-validation-action@ccb4328a959376b642e027874838f60f8e596de3
+      # The "Build with Gradle" step does a build using the `gradle/gradle-build-action` action provided by the Gradle organization on {% data variables.product.prodname_dotcom %}. The action takes care of invoking Gradle, collecting results, and caching state between jobs. For more information see [`gradle/gradle-build-action`](https://github.com/gradle/gradle-build-action).
       - name: Build with Gradle
         uses: gradle/gradle-build-action@749f47bda3e44aa060e82d7b3ef7e40d953bd629
         with:
           arguments: build
 ```
 
-This workflow performs the following steps:
-
-1. The `checkout` step downloads a copy of your repository on the runner.
-1. The `setup-java` step configures the Eclipse Temurin (Java) 17 JDK by Eclipse Adoptium.
-1. The "Validate Gradle wrapper" step validates the checksums of Gradle Wrapper JAR files present in the source tree.
-1. The "Build with Gradle" step does a build using the `gradle/gradle-build-action` action provided by the Gradle organization on {% data variables.product.prodname_dotcom %}. The action takes care of invoking Gradle, collecting results, and caching state between jobs. For more information see [`gradle/gradle-build-action`](https://github.com/gradle/gradle-build-action).
-
-The default starter workflows are excellent starting points when creating your build and test workflow, and you can customize the starter workflow to suit your project’s needs.
-
-{% data reusables.actions.example-github-runner %}
-
 {% data reusables.actions.java-jvm-architecture %}
 
 ## Building and testing your code

content/actions/automating-builds-and-tests/building-and-testing-java-with-maven.md

@@ -15,8 +15,9 @@ topics:
   - Java
   - Maven
 shortTitle: Build & test Java with Maven
+layout: inline
 ---
- 
+
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
 ## Introduction
@@ -47,35 +48,34 @@ To get started quickly, you can choose the preconfigured Maven starter workflow
 
 You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository.
 
-```yaml copy
+```yaml annotate copy
+# {% data reusables.actions.workflows.workflow-syntax-name %}
 name: Java CI
 
+#
 on: [push]
-
+#
 jobs:
   build:
-    runs-on: ubuntu-latest
 
+    {% data reusables.actions.example-github-runner-comment %}
+    runs-on: ubuntu-latest
+#
     steps:
+      {% data reusables.actions.workflows.workflow-checkout-step-explainer %}
       - uses: {% data reusables.actions.action-checkout %}
+      {% data reusables.actions.workflows.setup-java-step-explainer %}
       - name: Set up JDK 17
         uses: {% data reusables.actions.action-setup-java %}
         with:
           java-version: '17'
           distribution: 'temurin'
+      # The "Build with Maven" step runs the Maven `package` target in non-interactive mode to ensure that your code builds, tests pass, and a package can be created.
       - name: Build with Maven
         run: mvn --batch-mode --update-snapshots package
 ```
 
-This workflow performs the following steps:
-
-1. The `checkout` step downloads a copy of your repository on the runner.
-1. The `setup-java` step configures the Eclipse Temurin (Java) 17 JDK by Eclipse Adoptium.
-1. The "Build with Maven" step runs the Maven `package` target in non-interactive mode to ensure that your code builds, tests pass, and a package can be created.
-
-The default starter workflows are excellent starting points when creating your build and test workflow, and you can customize the starter workflow to suit your project’s needs.
-
-{% data reusables.actions.example-github-runner %}
+{% data reusables.actions.workflows.starter-workflows %}
 
 {% data reusables.actions.java-jvm-architecture %}
 

content/actions/automating-builds-and-tests/building-and-testing-nodejs.md

@@ -16,8 +16,9 @@ topics:
   - Node
   - JavaScript
 shortTitle: Build & test Node.js
+layout: inline
 ---
- 
+
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
 ## Introduction
@@ -37,39 +38,49 @@ We recommend that you have a basic understanding of Node.js, YAML, workflow conf
 
 {% data variables.product.prodname_dotcom %} provides a Node.js starter workflow that will work for most Node.js projects. This guide includes npm and Yarn examples that you can use to customize the starter workflow. For more information, see the [Node.js starter workflow](https://github.com/actions/starter-workflows/blob/main/ci/node.js.yml).
 
-To get started quickly, add the starter workflow to the `.github/workflows` directory of your repository. The workflow shown below assumes that the default branch for your repository is `main`.
+{% data reusables.actions.workflows.starter-workflows %}
 
-```yaml copy
+To get started quickly, add the starter workflow to the `.github/workflows` directory of your repository.
+
+```yaml annotate copy
+# {% data reusables.actions.workflows.workflow-syntax-name %}
 name: Node.js CI
 
+# This example workflow assumes that the default branch for your repository is `main`. If the default branch has a different name, edit this example and add your repository's default branch.
 on:
   push:
     branches: [ main ]
   pull_request:
     branches: [ main ]
 
+#
 jobs:
   build:
 
+    {% data reusables.actions.example-github-runner-comment %}
     runs-on: ubuntu-latest
 
+    # This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)."
     strategy:
       matrix:
         node-version: [14.x, 16.x, 18.x, 20.x]
-
+#
     steps:
+      {% data reusables.actions.workflows.workflow-checkout-step-explainer %}
       - uses: {% data reusables.actions.action-checkout %}
+      # This step uses the `actions/setup-node` action to set up Node.js for each version indicated by the `matrix.node-version` key above.
       - name: Use Node.js {% raw %}${{ matrix.node-version }}{% endraw %}
         uses: {% data reusables.actions.action-setup-node %}
         with:
           node-version: {% raw %}${{ matrix.node-version }}{% endraw %}
+      # This step runs `npm ci` to install any dependencies listed in your `package.json` file.
       - run: npm ci
+      # This step runs the `build` script if there is one specified under the `scripts` key in your `package.json` file.
       - run: npm run build --if-present
+      # This step runs the `test` script that is specified under the `scripts` key in your `package.json` file.
       - run: npm test
 ```
 
-{% data reusables.actions.example-github-runner %}
-
 ## Specifying the Node.js version
 
 The easiest way to specify a Node.js version is by using the `setup-node` action provided by {% data variables.product.prodname_dotcom %}. For more information see, [`setup-node`](https://github.com/actions/setup-node/).
@@ -178,7 +189,7 @@ steps:
   run: yarn --frozen-lockfile
 ```
 
-Alternatively, you can install the dependencies defined in the _package.json_ file. 
+Alternatively, you can install the dependencies defined in the _package.json_ file.
 
 ```yaml copy
 steps:

content/actions/using-workflows/workflow-syntax-for-github-actions.md

@@ -25,7 +25,7 @@ You must store workflow files in the `.github/workflows` directory of your repos
 
 ## `name`
 
-The name of your workflow. {% data variables.product.prodname_dotcom %} displays the names of your workflows on your repository's "Actions" tab. If you omit `name`, {% data variables.product.prodname_dotcom %} sets it to the workflow file path relative to the root of the repository.
+{% data reusables.actions.workflows.workflow-syntax-name %}
 
 {% ifversion actions-run-name %}
 
@@ -236,7 +236,7 @@ The value of this parameter is a string specifying the data type of the input. T
 
 ### Setting the `GITHUB_TOKEN` permissions for all jobs in a workflow
 
-You can specify `permissions` at the top level of a workflow, so that the setting applies to all jobs in the workflow. 
+You can specify `permissions` at the top level of a workflow, so that the setting applies to all jobs in the workflow.
 
 #### Example: Setting the `GITHUB_TOKEN` permissions for an entire workflow
 

data/reusables/actions/example-github-runner-comment.md

@@ -0,0 +1,8 @@
+# <!-- This is a YAML comment for use in annotated code examples. -->
+# You can run this workflow using a different operating systems.
+#
+# The starter workflow configures jobs to run on Linux, using the {% data variables.product.prodname_dotcom %}-hosted `ubuntu-latest` runners. You can change the `runs-on` key to run your jobs on a different operating system.
+#
+# For example, you can use the {% data variables.product.prodname_dotcom %}-hosted Windows runners by specifying `runs-on: windows-latest`. Or, you can run on the {% data variables.product.prodname_dotcom %}-hosted macOS runners using `runs-on: macos-latest`.
+#
+# You can also run jobs in Docker containers, or you can provide a self-hosted runner that runs on your own infrastructure. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)."

data/reusables/actions/workflows/setup-java-step-explainer.md

@@ -0,0 +1 @@
+# This step uses the `actions/setup-java` action to configure the Eclipse Temurin (Java) 17 JDK by Eclipse Adoptium.

data/reusables/actions/workflows/starter-workflows.md

@@ -0,0 +1 @@
+The default starter workflows are excellent starting points when creating your build and test workflow, and you can customize the starter workflow to suit your project’s needs.

data/reusables/actions/workflows/workflow-checkout-step-explainer.md

@@ -0,0 +1 @@
+# This step uses the `actions/checkout` action to download a copy of your repository on the runner.

data/reusables/actions/workflows/workflow-syntax-name.md

@@ -0,0 +1 @@
+The name of the workflow. {% data variables.product.prodname_dotcom %} displays the names of your workflows under your repository's "Actions" tab. If you omit `name`, {% data variables.product.prodname_dotcom %} displays the workflow file path relative to the root of the repository.