Learn module refresh -- Build continuous integration (CI) workflows b…

…y using GitHub Actions (#51)

* Learn module refresh -- Build continuous integration (CI) workflows by using GitHub Actions

* refreshing per current UI

* Apply suggestions from code review

slight edits per the style guide

---------

Co-authored-by: cmwilson21 <[email protected]>

.github/steps/1-add-a-test-workflow.md

@@ -10,36 +10,36 @@
 
 _Welcome to "GitHub Actions: Continuous Integration"! :wave:_
 
-**What is _continuous integration_?**: [Continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) can help you stick to your team’s quality standards by running tests and reporting the results on GitHub. CI tools run builds and tests, triggered by commits. The results post back to GitHub in the pull request. The goal is fewer issues in `main` and faster feedback as you work.
+**What is _continuous integration_?**: [Continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) can help you stick to your team’s quality standards by running tests and reporting the results on GitHub. CI tools run builds and tests, triggered by commits. The quality results post back to GitHub in the pull request. The goal is fewer issues in `main` and faster feedback as you work.
 
-![An illustration split in two. On the left: illustration of how GitHub Actions terms are encapsulated. At the highest level: workflows and event triggers. Inside of workflows: jobs and definition of the build environment. Inside jobs: steps. Inside steps: a call to an action. On the right: the sequence: workflows, job, step, action.](https://user-images.githubusercontent.com/6351798/88589835-f5ce0900-d016-11ea-8c8a-0e7d7907c713.png)
+![An illustration with a left half and a right half. On the left: illustration of how GitHub Actions terms are encapsulated. At the highest level: workflows and event triggers. Inside workflows: jobs and definition of the build environment. Inside jobs: steps. Inside steps: a call to an action. On the right: the evaluated sequence: workflow, job, step, action.](https://user-images.githubusercontent.com/6351798/88589835-f5ce0900-d016-11ea-8c8a-0e7d7907c713.png)
 
-- **Workflow**: A workflow is a unit of automation from start to finish, including the definition of what triggers the automation, what environment or other aspects should be taken into account during the automation, and what should happen as a result of the trigger.
+- **Workflow**: A workflow is a unit of automation from its start to finish, including the definition of what triggers the automation, what environment or other aspects should be taken into account during the automation, and what should happen as a result of the trigger.
 - **Job**: A job is a section of the workflow, and is made up of one or more steps. In this section of our workflow, the template defines the steps that make up the `build` job.
 - **Step**: A step represents one _effect_ of the automation. A step could be defined as a GitHub Action, or another unit, like printing something to the console.
-- **Action**: An action is a piece of automation written in a way that is compatible with workflows. Actions can be written by GitHub, by the open source community, or you can write them yourself!
+- **Action**: An action is a piece of automation written in a way that is compatible with workflows. Actions can be written by GitHub, by the open source community, and you can write them yourself!
 
-To learn more, check out "[Workflow syntax for GitHub Actions](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions)" in the GitHub Docs.
+To learn more, check out [Workflow syntax for GitHub Actions](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the GitHub Docs.
 
-First, let's add a workflow to lint our Markdown files in this repository.
+First, let's add a workflow to *lint* (clean, like a lint roller) our Markdown files in this repository. This workflow has a deliberate error in it ("npx" should be "npm"), which we'll debug in the next unit.
 
 ### :keyboard: Activity: Add a test workflow
 
-1. Open a new browser tab, and work on the steps in your second tab while you read the instructions in this tab
+1. Open a new browser tab, and work through the following steps in that tab while you read the instructions in this tab.
 1. Go to the **Actions tab**.
 1. Click **New workflow**.
 1. Search for "Simple workflow" and click **Configure**.
 1. Name your workflow `ci.yml`.
-1. Update the workflow to remove all steps other than the "checkout" step.
-1. Add the following step to your workflow:
+1. Update the workflow by deleting the last two steps.
+1. Add the following step at the end of your workflow:
    ```yml
    - name: Run markdown lint
      run: |
        npm install remark-cli remark-preset-lint-consistent
        npx remark . --use remark-preset-lint-consistent --frail
    ```
    > Even after the code is indented properly in `ci.yml`, you will see a build error in GitHub Actions. We'll fix this in the next step.
-1. Click **Start commit**, and choose to make a new branch named `ci`.
-1. Click **Propose a new file**.
+1. Click **Commit changes...**, and choose to make a new branch named `ci`.
+1. Click **Propose changes**.
 1. Click **Create pull request**.
-1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.
+1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/actions) will automatically update to the next step.

.github/steps/2-fix-the-test.md

@@ -14,11 +14,11 @@ When a GitHub Actions workflow is running, you should see some checks in progres
 
 <img alt="checks in progress in a merge box" src=https://user-images.githubusercontent.com/16547949/66080348-ecc5f580-e533-11e9-909e-c213b08790eb.png width=400 />
 
-You can follow along as GitHub Actions runs your job by going to the **Actions** tab or by clicking on "Details" in the merge box below.
+You can follow along as GitHub Actions runs your job by going to the **Actions** tab or by clicking "Details" in the merge box below.
 
-When the tests finish, you'll see a red X :x: or a green check mark :heavy_check_mark: in the merge box. At that point, you'll have access to logs for the build job and its associated steps.
+When the tests finish, you'll see a red X :x: or a green check mark :heavy_check_mark: in the merge box. At that point, you can access the logs for the build job and its associated steps.
 
-_By looking at the logs, can you identify which tests failed?_ To find it, go to one of the failed builds and scrolling through the log. Look for a section that lists all the unit tests. We're looking for the name of the test with an "x".
+_By looking at the logs, can you identify which tests failed?_ To find it, go to one of the failed builds and scroll through the log. Look for a section that lists all the unit tests. We're looking for the name of the test with an "x".
 
 <img alt="screenshot of a sample build log with the names of the tests blurred out" src=https://user-images.githubusercontent.com/16547949/65922013-e740a200-e3b1-11e9-8151-faf52c30201e.png width=400 />
 
@@ -31,8 +31,8 @@ If the checks don't appear or if the checks are stuck in progress, there's a few
 ### :keyboard: Activity: Fix the test
 
 1. Update the code in the `ci` branch to get the test to pass. You need to look something like this:
-   ```markdown
-   _underscore_
-   ```
+  ```markdown
+  _underscore_
+  ```
 1. **Commit changes**.
-1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.
+1. Wait about 20 seconds and then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/actions) will automatically update to the next step.

.github/steps/3-upload-test-reports.md

@@ -8,7 +8,7 @@
 
 _The workflow has finished running! :sparkles:_
 
-So what do we do when we need the work product of one job in another? We can use the built-in [artifact storage](https://docs.github.com/en/actions/advanced-guides/storing-workflow-data-as-artifacts) to save artifacts created from one job to be used in another job within the same workflow.
+So what do we do when we need the work product of one job in another? We can use the built-in [artifact storage](https://docs.github.com/actions/advanced-guides/storing-workflow-data-as-artifacts) to save artifacts created from one job to be used in another job within the same workflow.
 
 To upload artifacts to the artifact storage, we can use an action built by GitHub: [`actions/upload-artifacts`](https://github.com/actions/upload-artifact).
 
@@ -17,6 +17,7 @@ To upload artifacts to the artifact storage, we can use an action built by GitHu
 1. Edit your workflow file.
 1. Update the `Run markdown lint` step in your `build` job to use `vfile-reporter-json` and output the results to `remark-lint-report.json`.
 1. Add a step to your `build` job that uses the `upload-artifact` action. This step should upload the `remark-lint-report.json` file generated by the updated `Run markdown lint` step.
+1. Your new `build` should look like this:
 
    ```yml
    build:
@@ -36,6 +37,6 @@ To upload artifacts to the artifact storage, we can use an action built by GitHu
    ```
 
 1. Commit your change to this branch.
-1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.
+1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/actions) will automatically update to the next step.
 
-Similar to the upload action to send artifacts to the storage, you can use another action built by GitHub to download these previously uploaded artifacts from the `build` job: [`actions/download-artifact`](https://github.com/actions/download-artifact). To save you time, we'll skip that step for this course.
+Like the upload action to send artifacts to the storage, you can use the download action to download these previously uploaded artifacts from the `build` job: [`actions/download-artifact`](https://github.com/actions/download-artifact). For brevity, we'll skip that step for this course.

.github/steps/4-add-branch-protections.md

@@ -14,13 +14,13 @@ Protected branches ensure that collaborators on your repository cannot make irre
 
 ### :keyboard: Activity: Add branch protections
 
-1. Go to **Branches** settings. You can navigate to that page manually by clicking on the right-most tab in the top of the repository called **Settings** and then clicking on **Branches**.
-1. Click on **Add rule** under "Branch protection rules".
+1. Go to **Branches** settings. You can navigate to that page manually by selecting the right-most tab in the top of the repository called **Settings** and then clicking **Branches**.
+1. Click **Add branch protection rule** under "Branch protection rules".
 1. Type `main` in **Branch name pattern**.
 1. Check **Require a pull request before merging**.
 1. Check **Require status checks to pass before merging**.
 1. Check all build and test jobs that you'd like to see in the newly visible gray box.
-1. Click **Create**.
+1. Click **Save changes**.
 1. _Once you turn on branch protection, Actions can no longer push directly to `main`. You'll need to open the next step on your own._
 
-<!-- Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step. -->
+<!-- Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/actions) will automatically update to the next step. -->

.github/steps/5-merge-your-pull-request.md

@@ -8,12 +8,15 @@
 
 _Almost there! :heart:_
 
-You can now [merge](https://docs.github.com/en/get-started/quickstart/github-glossary#merge) your pull request!
+You can now [merge](https://docs.github.com/get-started/quickstart/github-glossary#merge) your pull request!
 
 ### :keyboard: Activity: Merge your pull request
 
 1. Click **Merge pull request**.
 1. Delete the branch `ci` (optional).
 1. _Once you turn on branch protection, Actions can no longer push directly to `main`. You'll need to open the "finish" on your own._
+    1. Navigate to the `.github` directory.
+    1. Select the `steps` directory.
+    1. Open the `X-finish.md` file.
 
-<!-- Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step. -->
+<!-- Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/actions) will automatically update to the next step. -->

.github/steps/X-finish.md

@@ -21,5 +21,5 @@ Here's a recap of all the tasks you've accomplished in your repository:
 - Get more ideas of what you can do with [awesome actions](https://github.com/sdras/awesome-actions).
 - We'd love to hear what you thought of this course [in our discussion board](https://github.com/orgs/skills/discussions/categories/test-with-actions).
 - [Take another GitHub Skills course](https://github.com/skills).
-- [Read the GitHub Getting Started docs](https://docs.github.com/en/get-started).
+- [Read the GitHub Getting Started docs](https://docs.github.com/get-started).
 - To find projects to contribute to, check out [GitHub Explore](https://github.com/explore).

.github/workflows/0-welcome.yml

@@ -4,14 +4,14 @@ name: Step 0, Welcome
 # This workflow updates from step 0 to step 1.
 
 # This will run every time we create push a commit to `main`.
-# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/actions/learn-github-actions/events-that-trigger-workflows
 on:
   workflow_dispatch:
   push:
     branches:
       - main
 
-# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/actions/security-guides/automatic-token-authentication
 permissions:
   # Need `contents: read` to checkout the repository.
   # Need `contents: write` to update the step metadata.
@@ -38,8 +38,8 @@ jobs:
     # We will only run this action when:
     # 1. This repository isn't the template repository.
     # 2. The step is currently 0.
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions
+    # Reference: https://docs.github.com/actions/learn-github-actions/contexts
+    # Reference: https://docs.github.com/actions/learn-github-actions/expressions
     if: >-
       ${{ !github.event.repository.is_template
           && needs.get_current_step.outputs.current_step == 0 }}

.github/workflows/1-add-a-test-workflow.yml

@@ -4,7 +4,7 @@ name: Step 1, Add a test workflow
 # This workflow updates from step 1 to step 2.
 
 # This will run every time we push to the ci.yml file on the ci branch.
-# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/actions/learn-github-actions/events-that-trigger-workflows
 on:
   workflow_dispatch:
   push:
@@ -13,7 +13,7 @@ on:
     paths:
       - .github/workflows/ci.yml
 
-# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/actions/security-guides/automatic-token-authentication
 permissions:
   # Need `contents: read` to checkout the repository.
   # Need `contents: write` to update the step metadata.
@@ -40,8 +40,8 @@ jobs:
     # We will only run this action when:
     # 1. This repository isn't the template repository.
     # 2. The step is currently 1.
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions
+    # Reference: https://docs.github.com/actions/learn-github-actions/contexts
+    # Reference: https://docs.github.com/actions/learn-github-actions/expressions
     if: >-
       ${{ !github.event.repository.is_template
           && needs.get_current_step.outputs.current_step == 1 }}

.github/workflows/2-fix-the-test.yml

@@ -4,7 +4,7 @@ name: Step 2, Fix the test
 # This workflow updates from step 2 to step 3.
 
 # This will run every time we push to README.md on the ci branch.
-# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/actions/learn-github-actions/events-that-trigger-workflows
 on:
   workflow_dispatch:
   push:
@@ -14,7 +14,7 @@ on:
       - README.md
       - resume.md
 
-# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/actions/security-guides/automatic-token-authentication
 permissions:
   # Need `contents: read` to checkout the repository.
   # Need `contents: write` to update the step metadata.
@@ -41,8 +41,8 @@ jobs:
     # We will only run this action when:
     # 1. This repository isn't the template repository.
     # 2. The step is currently 2.
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions
+    # Reference: https://docs.github.com/actions/learn-github-actions/contexts
+    # Reference: https://docs.github.com/actions/learn-github-actions/expressions
     if: >-
       ${{ !github.event.repository.is_template
           && needs.get_current_step.outputs.current_step == 2 }}

.github/workflows/3-upload-test-reports.yml

@@ -4,7 +4,7 @@ name: Step 3, Upload test reports
 # This workflow updates from step 3 to step 4.
 
 # This will run every time we push to the ci.yml file on the ci branch.
-# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/actions/learn-github-actions/events-that-trigger-workflows
 on:
   workflow_dispatch:
   push:
@@ -13,7 +13,7 @@ on:
     paths:
       - .github/workflows/ci.yml
 
-# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/actions/security-guides/automatic-token-authentication
 permissions:
   # Need `contents: read` to checkout the repository.
   # Need `contents: write` to update the step metadata.
@@ -40,8 +40,8 @@ jobs:
     # We will only run this action when:
     # 1. This repository isn't the template repository.
     # 2. The step is currently 3.
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions
+    # Reference: https://docs.github.com/actions/learn-github-actions/contexts
+    # Reference: https://docs.github.com/actions/learn-github-actions/expressions
     if: >-
       ${{ !github.event.repository.is_template
           && needs.get_current_step.outputs.current_step == 3 }}

.github/workflows/4-add-branch-protections.yml

@@ -4,15 +4,15 @@ name: Step 4, Add branch protections
 # This workflow updates from step 4 to step 5.
 
 # This will run every time we turn on or edit a branch protection rule.
-# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/actions/learn-github-actions/events-that-trigger-workflows
 on:
   workflow_dispatch:
   branch_protection_rule:
     types:
       - created
       - edited
 
-# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/actions/security-guides/automatic-token-authentication
 permissions:
   # Need `contents: read` to checkout the repository.
   # Need `contents: write` to update the step metadata.
@@ -39,8 +39,8 @@ jobs:
     # We will only run this action when:
     # 1. This repository isn't the template repository.
     # 2. The step is currently 4.
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts
-    # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions
+    # Reference: https://docs.github.com/actions/learn-github-actions/contexts
+    # Reference: https://docs.github.com/actions/learn-github-actions/expressions
     if: >-
       ${{ !github.event.repository.is_template
           && needs.get_current_step.outputs.current_step == 4 }}