Update course format for accessibility

skills · May 30, 2023 · c85a056 · c85a056
1 parent e3a587e
commit c85a056
Show file tree

Hide file tree

Showing 7 changed files with 59 additions and 62 deletions.
diff --git a/.github/script/STEP → .github/steps/-step.txt b/.github/script/STEP → .github/steps/-step.txt
diff --git a/.github/steps/0-welcome.md b/.github/steps/0-welcome.md
@@ -0,0 +1 @@
+<!-- readme -->
diff --git a/.github/workflows/0-start.yml → .github/workflows/0-welcome.yml b/.github/workflows/0-start.yml → .github/workflows/0-welcome.yml
@@ -1,25 +1,24 @@
-name: Step 0, Start
+name: Step 0, Welcome
 
 # This step triggers after the learner creates a new repository from the template
-# This step sets STEP to 1
-# This step closes <details id=0> and opens <details id=1>
+# 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/en/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/en/actions/security-guides/automatic-token-authentication
 permissions:
  # Need `contents: read` to checkout the repository
  # Need `contents: write` to update the step metadata
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -29,7 +28,7 @@ jobs:
  uses: actions/checkout@v3
  - id: get_step
  run: |
- echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT
+ echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT
  outputs:
  current_step: ${{ steps.get_step.outputs.current_step }}
 
@@ -39,9 +38,9 @@ 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
+ # 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
  if: >-
  ${{ !github.event.repository.is_template
  && needs.get_current_step.outputs.current_step == 0 }}
@@ -60,7 +59,7 @@ jobs:
  - name: Prepare a branch
  run: |
  echo "Make sure we are on step 0"
- if [ "$(cat .github/script/STEP)" != 0 ]
+ if [ "$(cat .github/steps/-step.txt)" != 0 ]
  then
  echo "Current step is not 0"
  exit 0
@@ -83,10 +82,9 @@ jobs:
  env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
- # Update README to close <details id=0> and open <details id=1>
- # and set STEP to '1'
- - name: Update to step 1
- uses: skills/action-update-step@v1
+ # In README.md, switch step 0 for step 1.
+ - name: Update to step 1
+ uses: skills/action-update-step@v2
  with:
  token: ${{ secrets.GITHUB_TOKEN }}
  from_step: 0

diff --git a/.github/workflows/1-create-the-workflow-file.yml b/.github/workflows/1-create-the-workflow-file.yml
@@ -1,11 +1,10 @@
 name: Step 1, Create the workflow file
 
 # This step triggers after the user creates `publish.yml` on branch `cd`
-# This step sets STEP to 2
-# This step closes <details id=1> and opens <details id=2>
+# This workflow updates from step 1 to step 2.
 
 # This will run every time we push `publish.yml` on branch `cd`
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
 on:
  workflow_dispatch:
  push:
@@ -14,14 +13,14 @@ on:
  paths:
  - .github/workflows/publish.yml
 
-# Reference https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
 permissions:
  # Need `contents: read` to checkout the repository
  # Need `contents: write` to update the step metadata
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -31,7 +30,7 @@ jobs:
  uses: actions/checkout@v3
  - id: get_step
  run: |
- echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT
+ echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT
  outputs:
  current_step: ${{ steps.get_step.outputs.current_step }}
 
@@ -41,9 +40,9 @@ 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
+ # 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
  if: >-
  ${{ !github.event.repository.is_template
  && needs.get_current_step.outputs.current_step == 1 }}
@@ -65,10 +64,9 @@ jobs:
  FILE: ".github/workflows/publish.yml"
  SEARCH: "docker/build-push-action"
 
- # Update README to close <details id=1> and open <details id=2>
- # and set STEP to '2'
- - name: Update to step 2
- uses: skills/action-update-step@v1
+ # In README.md, switch step 1 for step 2.
+ - name: Update to step 2
+ uses: skills/action-update-step@v2
  with:
  token: ${{ secrets.GITHUB_TOKEN }}
  from_step: 1

diff --git a/.github/workflows/2-add-a-dockerfile.yml b/.github/workflows/2-add-a-dockerfile.yml
@@ -1,11 +1,10 @@
 name: Step 2, Add a Dockerfile
 
 # This step triggers after we push changes to `Dockerfile` on branch `cd`
-# This step sets STEP to 3
-# This step closes <details id=2> and opens <details id=3>
+# This workflow updates from step 2 to step 3.
 
 # This will run every time we push changes to `Dockerfile` on branch `cd`
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
 on:
  workflow_dispatch:
  push:
@@ -14,14 +13,14 @@ on:
  paths:
  - Dockerfile
 
-# Reference https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
 permissions:
  # Need `contents: read` to checkout the repository
  # Need `contents: write` to update the step metadata
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -31,7 +30,7 @@ jobs:
  uses: actions/checkout@v3
  - id: get_step
  run: |
- echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT
+ echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT
  outputs:
  current_step: ${{ steps.get_step.outputs.current_step }}
 
@@ -41,9 +40,9 @@ 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
+ # 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
  if: >-
  ${{ !github.event.repository.is_template
  && needs.get_current_step.outputs.current_step == 2 }}
@@ -65,10 +64,9 @@ jobs:
  FILE: "Dockerfile"
  SEARCH: "FROM nginx:1.24-alpine"
 
- # Update README to close <details id=2> and open <details id=3>
- # and set STEP to '3'
- - name: Update to step 3
- uses: skills/action-update-step@v1
+ # In README.md, switch step 2 for step 3.
+ - name: Update to step 3
+ uses: skills/action-update-step@v2
  with:
  token: ${{ secrets.GITHUB_TOKEN }}
  from_step: 2

diff --git a/.github/workflows/3-merge-your-pull-request.yml b/.github/workflows/3-merge-your-pull-request.yml
@@ -1,25 +1,24 @@
 name: Step 3, Merge your pull request
 
 # This step triggers after pushing to main
-# This step sets STEP to 4
-# This step closes <details id=3> and opens <details id=4> <id=5> and <id=X>
+# This workflow updates from step 3 to step 4. <id=5> and <id=X>
 
 # This will run every time we push to main
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/en/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/en/actions/security-guides/automatic-token-authentication
 permissions:
  # Need `contents: read` to checkout the repository
  # Need `contents: write` to update the step metadata
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -29,7 +28,7 @@ jobs:
  uses: actions/checkout@v3
  - id: get_step
  run: |
- echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT
+ echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT
  outputs:
  current_step: ${{ steps.get_step.outputs.current_step }}
 
@@ -39,9 +38,9 @@ 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
+ # 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
  if: >-
  ${{ !github.event.repository.is_template
  && needs.get_current_step.outputs.current_step == 3 }}
@@ -56,11 +55,11 @@ jobs:
  with:
  fetch-depth: 0 # Let's get all the branches
 
- # Custom step finish here: close 3; open 4, 5, and X; set STEP to X
+ # Custom step finish here: close 3; open 4, 5, and X; set step to X
  - name: Update to open remaining steps
  run: |
  echo "Check that we are on FROM_STEP"
- if [ "$(cat .github/script/STEP)" != $FROM_STEP ]
+ if [ "$(cat .github/steps/-step.txt)" != $FROM_STEP ]
  then
  echo "Current step is not $FROM_STEP"
  exit 0
@@ -77,15 +76,15 @@ jobs:
  sed -r "s/<details id=([45X])>/<details id=\1 open>/g" README.md > tmp
  mv tmp README.md
 
- echo "Update the STEP file to TO_STEP"
- echo "$TO_STEP" > .github/script/STEP
+ echo "Update the step file to TO_STEP"
+ echo "$TO_STEP" > .github/steps/-step.txt
 
  echo "Commit the files, and push to main"
  git config user.name github-actions
  git config user.email github-actions@github.com
  git add README.md
- git add .github/script/STEP
- git commit --message="Update to $TO_STEP in STEP and README.md"
+ git add .github/steps/-step.txt
+ git commit --message="Update to $TO_STEPin step and README.md"
  git push
  env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

diff --git a/README.md b/README.md
@@ -10,12 +10,9 @@
 _Use GitHub Actions to publish your project to a Docker image._
 
 <!--
- <<< Author notes: Start of the course >>>
+ <<< Author notes: Course start >>>
  Include start button, a note about Actions minutes,
  and tell the learner why they should take the course.
- Each step should be wrapped in <details>/<summary>, with an `id` set.
- The start <details> should have `open` as well.
- Do not use quotes on the <details> tag attributes.
 -->
 
 <details id=0 open>
@@ -27,9 +24,15 @@ GitHub Actions makes it easier than ever to incorporate continuous delivery (CD)
 - **What you'll learn**: Continuous delivery, how to save and access build artifacts, package management, how to publish to GitHub Packages.
 - **What you'll build**: We will build a Docker image that runs a small game.
 - **Prerequisites**: We recommend you first complete the following courses: [Hello, GitHub Actions](https://github.com/skills/hello-github-actions) and [Continuous Integration](https://github.com/skills/continuous-integration).
-- **How long**: This course is five steps long and takes less than 30 minutes to complete.
+- **How long**: This course takes less than 30 minutes to complete.
 
-## How to start this course
+In this course, you will:
+
+1.
+2.
+3.
+
+### How to start this course
 
 <!-- For start course, run in JavaScript:
 'https://github.com/new?' + new URLSearchParams({