Map learning objectives to events

[github-learning-lab[bot]]

Events

Alright - you've chosen a project, and you've laid out the steps for your learners. Next, we're going to get into something new with Learning Lab: events! (You can learn more about events in the documentation.)

An event is the webhook that is triggered when the learner does something in their repository. Every webhook for the learner's repository is sent to Learning Lab. These events are "read" by Learning Lab. If it is the event the bot has been waiting for, the bot will do what you command. Otherwise, it will ignore the event. You can see all of the events in GitHub's documentation. Some of the most common examples are pull_request.synchronize or issue.comment.

Map behaviors to events

How can each step translate to a GitHub event? Having too many of the same event may be a bad signal. Make sure that events represent things that you're trying to teach.

For example, you may want to show a lot of information to the learner, and then have them close the issue to signify they've read it. That may make sense for one or two steps in your course. But, imagine going through a whole course like that. It isn't actually checking if the learner read - it's checking if the learner knows how to close issues!

Choose the right events

Try to choose events that correspond directly to what you want the learner to do. If you're trying to teach the learner to import a npm module into a package.json file, that commit should be the event.

Behavior	Events
What can I observe that confirms the user demonstrated the skill or knowledge?	What event triggers are available through GitHub?
Write a function (commit)	pull_request.synchronize
Solve a merge conflict (commit)	push
Open a pull request	pull_request
Implement a test	status
Comment on an issue	issue_commented.created

Step 5: Map learning objectives to events

Next, your job is to map your learning objectives to events.

Remember the steps you wrote earlier? Let's find the corresponding events. You'll see some are already done for the examples, but you can focus on your own.

:keyboard: Activity: Map the learning objectives you wrote to specific events from GitHub webhooks

1. Take a look through GitHub's documentation for event triggers.
2. Edit the config.yml file on line 29 and make note of the event trigger that matches your first objective.

Not sure where to start? Use some of the events in the table above to get started!

---

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

[github-learning-lab[bot]]

Outline the remaining steps

It is very important to choose events that correlate as directly as possible to what you're asking the learner to do. If you're not using gates* or other tests, the event should be what you're asking the learner to do.

One way to do this is to structure events using dot notation. For example, you could use an event called issue_comment. This means Learning Lab would be looking for any event related to an issue_comment, like created, edited, or deleted. But, you could also be more specific in the event description with dot notation. If you use issue_comment.created, Learning Lab will only move on if the event is a newly created issue comment.

_*Gates are an action within Learning Lab that allow you to use logic and verify the learner's behavior. We'll learn more about this later!

Step 6: Create an outline of learning objectives as events

Go ahead and put in the events for the rest of the learning objectives. You can use this time to re-order them in a way that makes sense to you for a flow of a course.

:keyboard: Activity: Using the same strategy of mapping learning objectives to events, create an outline of events for your course

1. Edit the config.yml file on lines 36, 43, 50, and 57.
2. Map the rest of your learning objectives to GitHub Events.

---

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

[github-learning-lab[bot]]

3 phases of a step

Have you ever thought about what teaching is? What are the behaviors that a good teacher has to make it easy to learn? Maybe you have - and maybe you haven't.

Let's break down teaching into three steps:

• telling the learner what to do
• watching them to see if they do it or not
• giving them specific feedback about what they did or didn't do right.

Repeat! That may sound simple, but it's the basis of fast feedback that is learning. :rainbow:

Just like we broke down your teaching goal into smaller steps, let's break down teaching in the same way. Let's focus on the smallest possible unit of behavior we can identify.

For starters, let's choose writing unordered lists in Markdown. That's what we want the user to know how to do. Let's apply those three phases.

Phase 1: Tell the learner what to do

What does the learner need to be able to exhibit the behavior that we want? Well, they'd need to know about Markdown, and it'd be nice if they had a computer with a keyboard, and a place to type the text. Let's assume those contextual things are taken care of. The main information that a learner would need would be, what is an unordered list? How is that written in Markdown? Then, we'd ask the user to do that.

Phase 2: The learner does it and we observe

There's an important part of this step. It's not just the learner doing it, but it's how we are going to watch and observe if they did it correctly or not. In Learning Lab, this is usually an issue comment or a commit changing a file. We give them the space to try it out, and we watch via webhooks. We use gates to "check" if they did what we asked them to.

Phase 3: Give the learner feedback

Based on the observation in the second phase, we can give them the feedback they need. We either confirm that they learned it, or let them know that they didn't do it right, and they should try again. It's important to give the most specific feedback as possible. This is like unit tests - if they're vague, they're not helpful. The more personalized and exact the feedback can be, the better the learner will understand what they did right and/or wrong.

How learning happens

This is how all learning happens, through feedback, whether it's from a teacher in a classroom, a bot like me, or a stovetop that gives you the feedback "if you touch me, it HURTS!". Faster and more exact feedback is always a better teacher.

This is the process that we are going to use for each of the learning objectives you've written.

Step 7: Choose the example that shows the three phases

Before we start writing some for this course, let's practice identifying this three phase process. There are four examples below - some of which are examples of this three phase process, and some of which aren't. For each example, there is a label. For each example that is a good example of the three phases, add the corresponding label to this pull request. Once all of them match what I expect, I'll give you the next instructions.

If you get stuck, add the issue label "help" and I'll give you some more detail.

:keyboard: Activity: Apply a label that corresponds to the example showing the three phases of a step

1. Read the following examples, and their corresponding "labels". (Click the triangle next to each title to drop down the full text.)
2. When an example correctly includes all three phases, add the corresponding label to this issue. (You can include multiple labels!)
   • Not sure how to add a label? On the right side of this issue, you'll see a section titled Labels. Click the word Labels to bring up a menu. Click a label title to toggle adding or removing it from an issue or pull request.
   • If you get stuck, apply the help label.

1: Committing a header

- **Phase 1**: We open a pull request for the learner that is adding a blank markdown file. We tell them what headers are, and show them examples of how to write them using markdown syntax. We ask them to commit a change to the file in the pull request adding a header. - **Phase 2**: The learner commits and changes the file. - **Phase 3**: We accept the learner's commit and move on to the next step.

2: Closing an issue

- **Phase 1**: We comment in an existing issue and ask the user to close that issue. We explain what closing an issue means, that issues can be reopened, and give examples of when it's appropriate to close an issue. - **Phase 2**: We use the webhook event specifically for closing issues. The learner closes an issue. We use a gate to validate that the correct issue is closed. Using this gate, we determine that the learner closed the wrong issue. - **Phase 3**: We reopen the issue that was closed but should have stayed open, and we comment telling the user that they closed the wrong issue. We link to the correct issue.

3: Fixing a bug

- **Phase 1**: We open a pull request for the learner in a repository with tests configured. The learner has already demonstrated the skills needed to understand the tests and the codebase. The pull request introduces a bug and has a failing test. We ask the learner to change the files in that pull request to fix the bug and make the tests pass. - **Phase 2**: The learner commits changes. We check using gates that the tests are passing, and that the tests haven't been removed. We see that the tests are passing. - **Phase 3**: We merge the pull request for the user and create the next task. We comment in the pull request congratulating them, and link them to their next instructions.

4: Writing a function

- **Phase 1**: We are teaching about writing functions, and we give the learner several examples in an issue comment. We ask the learner to write a function. - **Phase 2**: We assume the learner will create a branch, make a commit, and open a pull request. Then, we will use a gate to check their function. Because we ask the learner to do this in an issue, the learner is unsure of where to do this. They write a function as a comment in the issue. - **Phase 3**: Since we are listening for a commit, and the gate is set to check after that event, there is no feedback triggered when the user comments on the issue.

---

I'll respond below after you've added the correct labels.

[github-learning-lab[bot]]

Can't figure out which are the right labels? No worries! Here are the reasons and the answers:

Example 1: Committing a header 🛑

• Why?: This is not a proper example because it's missing an important part of step 2. While the user does change the file, we do not check that they do what we asked. They could have committed a list instead of a header! In phase 3, we move on to the next step, which is feedback to the learner that they did what we asked them. Now, the learner just learned that a list is a header. Do not apply this label.

Example 2: Closing an issue ✅

• Why?: In this example, we give the learner the instructions and the context they need to do what we want and understand why. We also see that the learner doesn't follow the instructions that we gave. That's OK because we notice it, and redirect them to try again. We reinforce the initial instructions, but with different and/or more specific terms to give the learner a greater chance of success, and ultimately, of learning what we want them to learn. Apply this label.

Example 3: Fixing a bug ✅

• Why?: This includes the directions for the learner, specific tests to make sure they've accomplished the goal, and direct feedback about their success. Note that there isn't a lot of context around the instructions, because the learner has gained that context in previous steps. Apply this label.

Example 4: Writing a function 🛑

• Why?: The instructions for this step aren't clear enough for the learner to be successful. The balance between assuming context and over-instructing was too far into assumption. The learner could become frustrated because they are following the instructions to the best of their ability, yet the course gives them no feedback. Do not apply this label.

[github-learning-lab[bot]]

3 Phases: Why?

If you'd like to know the reasons each option was or wasn't a good example, click the drop-down below.

Explanation of 3 phases

#### Example 1: Committing a header - **Why?**: This is not a proper example because it's missing an important part of step 2. While the user does change the file, we do not check that they do what we asked. They could have committed a list instead of a header! In phase 3, we move on to the next step, which is feedback to the learner that they did what we asked them. Now, the learner just learned that a list is a header. #### Example 2: Closing an issue - **Why?**: In this example, we give the learner the instructions and the context they need to do what we want _and_ understand why. We also see that the learner doesn't follow the instructions that we gave. That's OK because we notice it, and redirect them to try again. We reinforce the initial instructions, but with different and/or more specific terms to give the learner a greater chance of success, and ultimately, of learning what we want them to learn. #### Example 3: Fixing a bug - **Why?**: This includes the directions for the learner, specific tests to make sure they've accomplished the goal, and direct feedback about their success. Note that there isn't a lot of context around the instructions, because the learner has gained that context in previous steps. #### Example 4: Writing a function - **Why?**: The instructions for this step aren't clear enough for the learner to be successful. The balance between assuming context and over-instructing was too far into assumption. The learner could become frustrated because they are following the instructions to the best of their ability, yet the course gives them no feedback.

Writing responses

Let's do one together before we start going into the others. If the first learning objective is based on Issues - specifically, how to open one. What do we need to do in phase one to prompt the user to demonstrate that behavior in phase two?

Now is a good time to learn about responses. The response directory is where you store the files that will be what the bot says.

Step 8: Create the first response

To practice, I've got a file ready for you in this pull request. Go ahead and write your instructions (phase 1 for this objective) in the file in this pull request and commit.

You may notice the file name and structure. They represent the best practices we've found to make things clear for our users.

:keyboard: Activity: Write the first response, phase 1, for the first step of your course

1. Edit the 01_first-response.md file and write the instructions for your first step.
   • Remember, this is your course. You choose what to teach, what the steps are, and what to say!

---

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

[github-learning-lab[bot]]

3 Phases: Why?

If you'd like to know the reasons each option was or wasn't a good example, click the drop-down below.

Explanation of 3 phases

#### Example 1: Committing a header - **Why?**: This is not a proper example because it's missing an important part of step 2. While the user does change the file, we do not check that they do what we asked. They could have committed a list instead of a header! In phase 3, we move on to the next step, which is feedback to the learner that they did what we asked them. Now, the learner just learned that a list is a header. #### Example 2: Closing an issue - **Why?**: In this example, we give the learner the instructions and the context they need to do what we want _and_ understand why. We also see that the learner doesn't follow the instructions that we gave. That's OK because we notice it, and redirect them to try again. We reinforce the initial instructions, but with different and/or more specific terms to give the learner a greater chance of success, and ultimately, of learning what we want them to learn. #### Example 3: Fixing a bug - **Why?**: This includes the directions for the learner, specific tests to make sure they've accomplished the goal, and direct feedback about their success. Note that there isn't a lot of context around the instructions, because the learner has gained that context in previous steps. #### Example 4: Writing a function - **Why?**: The instructions for this step aren't clear enough for the learner to be successful. The balance between assuming context and over-instructing was too far into assumption. The learner could become frustrated because they are following the instructions to the best of their ability, yet the course gives them no feedback.

Writing responses

Let's do one together before we start going into the others. If the first learning objective is based on Issues - specifically, how to open one. What do we need to do in phase one to prompt the user to demonstrate that behavior in phase two?

Now is a good time to learn about responses. The response directory is where you store the files that will be what the bot says.

Step 8: Create the first response

To practice, I've got a file ready for you in this pull request. Go ahead and write your instructions (phase 1 for this objective) in the file in this pull request and commit.

You may notice the file name and structure. They represent the best practices we've found to make things clear for our users.

:keyboard: Activity: Write the first response, phase 1, for the first step of your course

1. Edit the 01_first-response.md file and write the instructions for your first step.
   • Remember, this is your course. You choose what to teach, what the steps are, and what to say!

---

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

[github-learning-lab[bot]]

Learning Lab Actions

Awesome! You're probably thinking - how is Learning Lab validating that I did the thing just now!? And you have a point. With text, it's tricky - so I checked to make sure you wrote more than 5 words, but I'm not checking to see if you wrote anything that makes sense. For this type of step, it would be difficult to provide great feedback on what you wrote.

Every comment that I make is an example of a real, human-proofed answer. Compare your answer and notice - is yours similar? Is it very different? What would you change?

Action type: respond

Now that you've written a response, we need to figure out how to say it to with Learning Lab. Now is the time to learn about Learning Lab's actions. Actions are reusable modules that each Learning Lab course has access to. They are each designed to do very specific things, and nothing more. This is to optimize for reusability and simplicity.

There are all kinds of actions. Learning Lab can do different things like responding, opening pull requests, merging, and more. You can see all of the available actions in Learning Lab's documentation.

Step 9: Write the first Learning Lab action

You've got the response file, and now it's time to edit the config file with the proper action: respond. Because this is the first instruction, it belongs in the "before" step. That way, the learner knows what we are waiting for them to do when they first enter the course. It will look like this:

    before:
    - type: respond
      with: 01_first-response.md

:keyboard: Activity: Write the first Learning Lab action for a response into your course's configuration file

1. Edit the config.yml file in this pull request on lines 17 and 18 to add a respond type, referencing the file that you created for the response.

---

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

[github-learning-lab[bot]]

Phase 2: Observation and Validation (with Gates)

Phase 2 is where we watch to see if the learner did what we asked them to do. With Learning Lab, we are watching for the event to be sent by GitHub and then checking to see if it was the event we were expecting.

The events that are sent to Learning Lab alert Learning Lab that something has happened. But, to create a good learning experience, we should validate that the learner did the right thing. For example, if we ask a learner to commit a function to a file, we'll get an event when they've committed to a branch. But we would receive the same trigger, but they may not have committed to the correct file! In these cases, use a gate action for validation. Gates can:

• Validate that a closed pull request was merged
• Check the contents of a comment or commit with regex
• Ensure an opened issue contains body text

A :book: gate is a Learning Lab action. Gates are conditionals, and they behave much like a conditional in Javascript.

You can also get creative here - maybe you want to include tests in the template repository. When the tests are run, the status could be the event that you check.

Step 10: Write a gate

As an example of how gates work, let's validate the learner's pull request title. This information is accessible to us :book: from the payload that is sent with the 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: Write a gate to check the user's first step

1. Edit the config.yml file on this branch around line 32.
2. Add a type: gate action on line 32.
3. Add a left: option to the gate.
4. Set the gate's left: option. This could be to the pull request's title ('%payload.pull_request.title%') or some other information from the payload based on the event trigger.
5. Set the gate's operator:, usually to ===.
6. Set the gate's right: to the title we expect, like the name of the pull request, or regex for what is expected from the commit contents, or any other amount which makes sense in your case.

---

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

Aren't sure what event and gate to use? No worries - you can borrow these:

- title: Assign yourself
  description: Assign the first issue to yourself.
  event: issues.assigned
  link: 'https://github.com/gitstua/lab-starter/issues/1'
  actions:
  - type: gate
    left: '%payload.pull_request.title%'
    operator: ===
    right: Add name to README

[github-learning-lab[bot]]

I noticed that your commit to the config.yml file doesn't have what I am expecting.

I'm using a gate and using regular expressions to check your commit. I'm literally checking for something like:

type: gate
left:
operator:
right:

But, each learner may have a different exact version. Yours may look like:

- type: gate
  left: '%payload.pull_request.title%'
  operator: ===
  right: "Creating the config file"

Try again by committing to the config.yml file on this branch, and make sure your changes match my example above. (Make sure your indentations are correct, too!)

[github-learning-lab[bot]]

Phase 3: Feedback

Nice, now you've got phases one and two covered. It's time for phase 3.

What you do in Phase 3 will be based on what you saw in phase 2. Let's keep it simple for now and have only two possibilities: either the user did it right, or they didn't. This structure is pretty basic, but if you use your imagination, you can probably envision more interesting possibilities.

Step 11: Write feedback for the learner

I just added two response files in this pull request - one for the "happy path" where the user did it right, and one to redirect them and give them help to get back on track. Fill in those response files now.

:keyboard: Activity: Write feedback into the feedback response for the learner to let them know they've done it right

1. Edit the feedback files in this pull request with feedback about the success of their behavior.
   1. The first file is called responses/01_nice-work.md
   2. The second file is called responses/01_try-again.md
2. Because you are editing multiple files, it will be difficult for me to see that you have modified them both. To let me know you're done, comment in this pull request.

---

I'll respond below after you comment on this pull request.

[gitstua]

done

[github-learning-lab[bot]]

I noticed that though the correct file is edited, there isn't a lot of substance. It's okay to come back and edit these responses later to make them longer or more complete. But, in the meantime, you should write enough so that you can go through the course as a learner and remember what is expected for each step.

Try again - Edit the 01_nice-work.md file with at least one sentence of instruction for yourself, then comment in this pull request.

---

I'll respond below after you comment on this pull request.

[gitstua]

ok

[github-learning-lab[bot]]

Config logic

To put this response in the config, it will be very similar to phase 1. But, where the action goes is different. We need to be careful of the gate here. If the gate fails, we can have special logic for the "unhappy path" response. The "happy path" response will be a regular response triggered if the gate is successful, like:

- type: gate
    left: '%payload.pull_request.base.ref%'
    operator: ===
    right: master
    else:
    - type: respond
      with: 01_try-again.md
- type: respond
  with: 01_nice-work.md

Step 12: Write the config logic

Go ahead and edit the config to add the unhappy path and the happy path response.

Are you noticing that we're asking a bit more of you now? Since you've already added a response before, we're now asking you to do two at a time. This is on purpose - it's important to balance how much you're asking learners to do. It's bad to bore them, but it's also really bad to overwhelm them. Every learner is different, so try to pick a "middle of the road" solution. This is ours. What do you think?

:keyboard: Activity: Write the config logic for both responses to the learner in their first step

1. Edit the config file in this pull request to include the logic for both responses around the gate.

---

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

[github-learning-lab[bot]]

I noticed that your commit to the config.yml file doesn't have what I am expecting.

I'm using a gate and using regular expressions to check that you have something committed that looks like:

type: respond
with: 01_nice-work.md

Try again by committing to the config.yml file on this branch, and make sure your changes match my example above.

[github-learning-lab[bot]]

I noticed that your commit to the config.yml file doesn't have what I am expecting.

I'm using a gate and using regular expressions to check that you have something committed that looks like:

type: respond
with: 01_nice-work.md

Try again by committing to the config.yml file on this branch, and make sure your changes match my example above.

[github-learning-lab[bot]]

Course metadata

Awesome work so far! Now, you've officially got your first step written. It's a good time to try this course out. Before we do, we need to pay some attention to the metadata in the config file, so that Learning Lab knows what to do with it.

The parts that we need now are the title, description, and the name of the learner's repository. Learning Lab also needs more detail around each step. The information is there in detail in comments in the config file.

Here are a few examples:

• Introduction to GitHub

  title: Introduction to GitHub
  description: If you are looking for a quick and fun introduction to GitHub, you've found it. This class will get you started using GitHub in less than an hour.
  template:
  name: github-slideshow
  repo: caption-this-template
  description: 'A robot powered training repository :robot:'

• Communicating Using Markdown

  title: "Communicating using Markdown"
  description: "This course will walk you through everything you need to start organizing ideas and collaborating using Markdown, a lightweight language for text formatting."
  template:
  name: "markdown-portfolio"
  repo: "communicating-using-md-template"

• This course - Writing a Learning Lab course

  title: Write a Learning Lab course
  description: Use Learning Lab's strengths for fast feedback to author your own course.
  template:
  name: lab-starter
  repo: write-a-ll-course-template

Step 13: Create course metadata

:keyboard: Activity: Add the course metadata like title and description to the configuration file

1. Edit the config file (lines 1, 2, and 3) so the comments are gone, and your information is there.

---

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

[github-learning-lab[bot]]

Nice job! I'll merge this pull request for you. Your next steps can be found in your next issue.