Write the course steps

[github-learning-lab[bot]]

Great! Now let's work on the before: block.

before:

Anything in this block occurs before the learner can access their course repository.

Learning Lab actions

Actions are reusable modules that each course has access to. They are each designed to do very specific things, and nothing more. This is to optimize for reusability and simplicity. The documentation contains a listing of :book: all available actions.

Step 7: Add to the before block

We'll use the :book: createIssue action to create an issue for the learner with some initial instructions. The createIssue action requires two :book: options:

• a title
• the body of the response

We'll define both of those here, but we'll create the body in the next step.

:keyboard: Activity: Add the createIssue action

1. Add a createIssue action in the before: block
   • Note: Since there are multiple suggested changes, you can go to the "Files changed" tab and accept them as a batch

---

I'll respond below when I detect a commit on this branch.

[github-learning-lab[bot]]

Great! Now, the repository will have an issue for the learner.

Step 9: Creating a response

In the last step, we referenced a file titled welcome-text.md, but it doesn't exist. Learning Lab automatically looks in the :book: responses/ directory for all content files. Let's add it.

:keyboard: Activity: Adding a response

1. In the /responses/ folder, create a new file titled welcome-text.md
   • Note: If you're working on GitHub.com, you may need to navigate to the Code tab, checkout to the write-steps branch, and click Create new file, or use this shortcut
2. In that file, add some content that will appear to the learner in the welcome issue
3. Add an instruction for the learner to open a new pull request titled "Add name to README" in which they add their name to the README file

---

I'll respond below when I detect a commit on this branch.

[github-learning-lab[bot]]

Great! The learner's repository will now be setup with a single issue.

Steps in Learning Lab

Let's now dive into the steps:. This block is composed of :book: steps that are triggered by events on GitHub, and in turn certain :book: actions take place. actions in this context are NOT the same as GitHub Actions.

Each step maps directly to something that the user will do. User interaction on GitHub triggers the step, and Learning Lab responds. The user interaction could be creating a pull request, closing an issue, or editing a file. When designing a course, it's important to plan for the user interactions to reflect what you want them to learn.

Best practices for steps

For example, you _could_ write a lot of text and have the user close the issue when they're done. But, unless your text was telling them how to close an issue, that reaction doesn't make sense. Try to find a way to have the user demonstrate their knowledge, like by committing a function to a branch. Let the user _show_ they understand to trigger the next step. See [:book: best practices](https://lab.github.com/docs/3-5-responses#best-practices) in the Learning Lab docs for more suggestions.

Step 9: Naming our first step

Let's name our first step. We will give it a title and a description. These will be shown on Learning Lab, and they help course authors stay organized in the config.yml file. The docs show :book: syntax and examples of how steps are shown to the learner.

:keyboard: Activity: Naming our first step

1. Add a title and description for the first step
   • Note: You can do this by editing the file, or accepting my suggested change

---

I'll respond below when I detect a commit on this branch.

[github-learning-lab[bot]]

Great! Your learner now has information about what they're expected to do in this step of the course.

Events

Every step in a course will be triggered by a GitHub Event. All possible events are documented in Events Types & Payloads on the GitHub Developer Guide.

Step 10: Add an event

Let's now find the event that will trigger the step. Because we want the learner to open a new Pull Request, the event we're looking for is pull_request. Whenever this event occurs, information about the pull request is delivered to Learning Lab. However, if we just write pull_request, any interaction with a pull request will cause this step to be triggered. We're specifically looking for the learner to open a pull request. We can filter the event to only opened pull requests by using pull_request.opened instead.

:keyboard: Add an event

1. Add a pull_request.opened event for the first step
   • Note: You can do this by editing the file, or accepting my suggested change

---

I'll respond below when I detect a commit on this branch.

[github-learning-lab[bot]]

Validation

The events that can act as triggers help Learning Lab know when something happens. However, sometimes knowing it happened isn't enough. For example, if we ask a learner to commit a function to a file, we'll get a trigger that they've committed to a branch. But we would receive the same trigger, even if they committed to a different file!

Course authors can use gates to be validate the user's completion of a step. A :book: gate is a Learning Lab action. Gates are conditionals, and they behave much like a conditional in Javascript. Let's add a gate, we'll specify its options in a later step.

Step 11: Add a gate

Let's now validate the learner's PR. We asked them to title the pull request "Add name to README" so that's what we need to validate against.

:keyboard: Activity: Adding a gate

1. Add a gate or accept the suggested change below

---

I'll respond below when I detect a commit on this branch.

[github-learning-lab[bot]]

Step 12: Add validation

We need to validate against the learner's pull request title. This information is accessible to us :book: from the payload that is sent with the event. In this case, the information was sent from a pull_request.opened event.

You can see an example of all the information sent in the GitHub Developer docs.

We'll add the :book: left: option to the gate, and compare its value to the expected pull request's title.

A completed example of this would look as follows, with comments on the right starting with a hash #:

actions:
- type: gate                            # using the gate action
  left: '%payload.pull_request.title%'  # get the title from the pull request object inside of the payload
  operator: ===                         # check for strict equality, see more at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators#Identity
  right: Add name to README             # this is the expected value

:keyboard: Activity: Adding validation

1. Add a left: option to the gate
2. Set the gate's left: option to the pull request's title which is '%payload.pull_request.title%'
3. Set the gate's operator: to ===
4. Set the gate's right: to the title we expect which is Add name to README

You can also accept the suggested changes below. To accept as a batch, go to the Files changed tab.

---

I'll respond below when I detect a commit on this branch.

[github-learning-lab[bot]]

When your learner is successful, gates let the actions that follow execute.

Step 13: Responding on success

Let's respond to the learner by commenting in their pull request. We'll let them know they've completed our course.

:keyboard: Activity: Responding to successful actions

1. In the same step, add a :book: respond action
2. Add a with: pr-opened.md option for the response file

You can also accept the suggested changes below. You don't need to worry about the pr-opened.md file, since we created it for you, but feel free to change its contents.

---

I'll respond below when I detect a commit on this branch.

[github-learning-lab[bot]]

Course README

Our last step is to create a :book: README.md file. This file will show on Learning Lab as users register. This file should contain learning outcomes and some long form content.

Step 14: Add a README.md file

We added a README for you, but go ahead and put in your own content.

:keyboard: Activity: Edit the README.md

1. Edit the README.md file to contain a description of the course
   • Note: If you're working on GitHub.com, you can click on the link above or navigate to the Code tab, checkout to the write-steps branch, and click Create new file

---

I'll respond below when I detect a commit on this branch.

[github-learning-lab[bot]]

Step 15: Submit your approval

The course repository is now ready to be finalized.

:keyboard: Activity: Approve the course steps

1. Approve this pull request.

---

I'll respond below when I detect an approval on this pull request.

[github-learning-lab[bot]]

Let's go to the next issue.