feat: Adjustments to include more learning material. Combines steps 4 and 5

Author: chriswblake

.github/steps/1-open-a-pull-request.md

@@ -2,18 +2,41 @@
 
 _Welcome to "Review pull requests"! :wave:_
 
-Let's get started by opening a pull request.
+Let's get started by opening a pull request on some changes that were recently added to the the `update-game` branch.
 
-**What is a pull request?**: Collaboration happens on a pull request. The pull request shows the changes in your branch to other people. This pull request is going to keep the changes you just made on your branch and propose applying them to the `main` branch.
+### What is a pull request?
+
+A **pull request** is a collaboration area where work in one branch is reviewed before merging it into another branch. It has 4 tabs to manage the conversation and easily review changes.
+
+- **Conversation** - A general log of the pull request activity. It also provides open space fellow collaborators and the community to provide ideas, suggestions, and general feedback.
+- **Committs** - A list of only the commits unique to the proposed branch.
+- **Checks** - The results of any automations applied to the pull request using [GitHub Actions](https://github.com/features/actions). That's for another lesson though. 😎
+- **Files Changed** - A [Diff](https://docs.github.com/en/get-started/quickstart/github-glossary#diff) view that easily shows the proposed changes in a before/after view. It also options to add comments and reviews in context.
+
+> [!TIP]
+> You can [create a draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for unfinished work. This can help avoid accidental merges or premature reviews.
 
 ### :keyboard: Activity: Create a pull request
 
-1. Click on the **Pull requests** tab in your repository.
-2. Click **New pull request**.
-3. In the **base:** dropdown, make sure **main** is selected.
-4. Select the **compare:** dropdown, and click `update-game`.
-5. Click **Create pull request**.
-6. Enter a title for your pull request: `Update the game over message`.
-7. Enter a description for your pull request: `Update the game over message so people know how to play again!`
-8. Click **Create pull request**.
-9. With the pull request created, Mona will check your progress then prepare and share the next steps.
+1. In the top navigation, select the **Pull requests** tab.
+
+1. On the right, click the **New pull request** button.
+
+1. Under the **Compare changes** area, select the following options and click the **Create pull request** button.
+
+   - **base:** `main`
+   - **compare:** `update-game`
+
+1. Set the **title** and **description** to the following.
+
+   ```md
+   Update the game over message
+   ```
+
+   ```md
+   Update the game over message so people know how to play again!
+   ```
+
+1. Click **Create pull request**.
+
+1. With the pull request created, Mona will check your progress and share the next steps.

.github/steps/2-assign-yourself.md

@@ -2,15 +2,15 @@
 
 _Great job opening that pull request! :wave:_
 
-**What is a _pull request review_?**: Reviewing a pull request is an opportunity to examine another contributor's changes and give them feedback. It's an awesome opportunity to learn more about how the project works and how others solve problems.
+#### What is an assignee?
 
-The best way to get a review is to ask for one. On GitHub, you can ask someone to review a pull request by assigning them as a reviewer or assignee. If you are not ready for review, consider [creating a draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) instead.
+A **pull request assignee** is the person (or persons) most familiar with the the proposed changes.
+It's a simple mechanism for keeping track of who to contact for questions.
 
 ### :keyboard: Activity: Assign yourself
 
-1. Open the pull request you just created.
-1. Under **Assignees** on the right side of the screen, add yourself.
+1. If not on the created pull request, navigate back to it.
 
-   Because you created the pull request, you can't assign yourself as a reviewer, but feel free to assign a friend as a reviewer instead to see how it works :smile:
+1. On the right side, under **Assignees**, click the **assign yourself** text.
 
-1. With the pull request assigned, Mona will check your progress then prepare and share the next steps.
+1. After assigning yourself, Mona will check your progress and share the next steps.

.github/steps/3-leave-a-review.md

@@ -2,15 +2,29 @@
 
 _You assigned yourself! :tada:_
 
-Pull request reviews ensure quality and maintain momentum of changes to your project.
+#### What is a pull request review?
 
-#### When reviewing a pull request:
+A **pull request review** is feedback from other collaborators or community members on the proposed changes. It helps ensure quality and project momentum. Even more importantly, it's an awesome opportunity to learn more about the project and grow as a developer by seeing how others approach the problem.
 
-1. Review the _title_ and _body_ of the pull request, and possibly any associated issue, to understand the intended change.
-1. Review the [diff](https://docs.github.com/en/get-started/quickstart/github-glossary#diff), the comparison of the proposed code, in the context of the whole project.
-1. For most things, try out the proposed change. Check if the actual change matches the intention. Find the repository's [contributing guide](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) to find out how to review the changes.
+Naturally, the best way to get a review is to ask for one. By assigning a reviewer they get 3 options for providing feedback:
 
-#### In your review comments:
+- **Comment** - General feedback without approval or rejection.
+- **Approve** - Allows merging if [rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), [code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners), or other policies are enforced.
+- **Request Changes** - The proposed changes need continued work and review should be re-requested.
+
+The **Files changed** tab is the primary place for collecting feedback. It allows for adding comments directly to lines before submitting a review.
+
+### What does a review typically loook like?
+
+1. Reviewing the **title** and **description** are clear and concise. It should easily convey the intended changes and any associated issues.
+
+1. Reviewing the **Files changed** tab to ensure all proposed code matches the description.
+
+1. For most things, try out the proposed change to verify the they matche the intention.
+
+1. Use the repository's [contributing guide](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) for any guidance on review requirements, testing, quality verification, etc.
+
+#### Review ideas
 
 - Identify potential issues, risks, and limitations.
 - Suggest changes and improvements.
@@ -21,13 +35,22 @@ Pull request reviews ensure quality and maintain momentum of changes to your pro
 - Be concise _and_ provide meaningful detail.
 - Treat the pull request author with kindness and empathy.
 
-When an approval or request for changes is not yet needed, consider using **comments**. An **approval** lets the author know you believe the pull request is safe to merge. **Requesting changes** lets the author know you believe the pull request is not ready to merge.
-
 ### :keyboard: Activity: Leave a review
 
-1. On the pull request, click **Files changed**.
-1. Click **Review changes**.
-1. Add a comment with your initial thoughts on the pull request.
-1. Select _comment_. You won't be able to _approve_ or _request changes_ to your own pull request.
-1. Click **Submit review**.
-1. With the review submitted, Mona will check your progress then prepare and share the next steps.
+1. On the pull request, click the **Files changed** tab.
+
+1. Take a moment to review the change.
+
+   - Notice the change is a simple wording adjustment.
+
+1. Above the comparison view, click the **Review changes** button.
+
+1. Enter the following comment and click the **Submit review** button.
+
+   ```md
+   Looks good to me. I think this is more intuitive. Nice work!
+   ```
+
+   > 🪧 **Note:** You can't choose **Approve** or **Request changes** because your created the pull request.
+
+1. With your review submitted, Mona will check your progress and share the next steps.

.github/steps/4-suggest-changes.md

@@ -2,18 +2,40 @@
 
 _Nice work reviewing that pull request :sparkles:_
 
-Now that you have explored the different ways you can review a pull request it is time to learn how to use _suggest changes_.
+While reviewing, it is very common to find simple changes that are easier to implement than to describe. For example typos or rewording sentences. These are perfect situations for the **Add a suggestion** feature.
 
-**What is _suggest changes_?**: This feature enables you to recommend a change to a pull request that the author can commit with the push of a button.
+### How do I suggest a change?
+
+The **Add a suggestion** feature is a button in the comment text editor. It inserts a specially formatted code block. Instead of only showing a comment, GitHub will also provide a **Commit changes** button. This allows the author to accept the suggestion and commit it with the push of a button. No need to open a code editor! Nice!
 
 ### :keyboard: Activity: Suggest changes
 
 1. On the pull request, click **Files changed**.
-1. Find the `index.html` changes.
+
+1. Find the comparison view for the `index.html` file and find the modified line.
+
 1. Hover your cursor next to the line numbers on the left side of the page.
-1. Click the blue plus icon.
-1. After the comment form appears, click the **Add a suggestion** button. <br>
-   ![add-a-suggestion-button](https://user-images.githubusercontent.com/97056108/184449714-61e8ee51-824a-48c1-9436-2dfd67f2c070.png)
-1. Edit the suggestion.
-1. Click **Add a single comment**.
-1. With commented added, Mona will check your progress then prepare and share the next steps.
+
+1. Click the plus icon to review an inline comment form.
+
+1. Click the **Add a suggestion** button to insert a modifiable copy of the line.
+
+   <img width="300" alt="add-a-suggestion-button" src="https://github.com/user-attachments/assets/dc781d29-d5fe-4da9-9e4b-eb406c5d9ab5" />
+
+1. Edit the suggestion to match below and click the **Add a single comment** button.
+
+   ````md
+   ```suggestion
+   <h2 hidden>Game over! Want to play again?! Just click refresh. 🧑‍🚀!</h2>
+   ```
+
+   Let's make it a bit more friendly. 🤓
+   ````
+
+### :keyboard: Activity: Apply a suggested change
+
+1. Click the **Commit suggestion** button to open a form for adding a commit message.
+
+1. Enter the following commit message and click the **Commit changes** button.
+
+1. With the changes committed, Mona will check your progress then prepare and share the next steps.

.github/steps/5-apply-changes.md

@@ -0,0 +1,15 @@
+## Step 6: Merge your pull request
+
+_Almost there!_ :heart:
+
+With our reviews collected and feedback implemented, it's time to merge the changes.
+
+### :keyboard: Activity: Merge your pull request
+
+1. In the pull request navigation, select the **Conversation** tab.
+
+1. Scroll down and click the **Merge** button.
+
+1. (optional) Delete the `update-game` branch.
+
+1. With the pull request merged, Mona will check your progress and prepare a final review. Congrats you are done! 🎉

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

@@ -11,7 +11,7 @@ permissions:
   issues: write
 
 env:
-  STEP_5_FILE: ".github/steps/5-apply-changes.md"
+  STEP_5_FILE: ".github/steps/5-merge-your-pull-request.md"
 
 jobs:
   find_exercise:

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

@@ -1,4 +1,4 @@
-name: Step 6
+name: Step 5
 
 on:
   pull_request: