Merge pull request #9 from githubtraining/fix-links

Tell a cohesive story

Author: hectorsector

config.yml

@@ -57,33 +57,44 @@ steps:
     event: issues.closed
     link: '{{ repoUrl }}/issues/1'
     actions:
+      - type: gate
+        left: '%payload.issue.title%'
+        operator: ===
+        right: Welcome to this repository
+        else:
+        - type: respond
+          with: e-unexpected.md
+          data:
+            expected: close the issue titled **Welcome to this repository**
       - type: createIssue
-        title: Find the similar issue
-        body: 01_crosslink.md
+        title: Fix the sidebar
+        body: 01_sidebar.md
+        comments:
+        - 01_crosslink.md
         action_id: similarIssue
       - type: createProjectBoard
         name: v1.0.0
         description: Planning for v1.0.0 release
         columns:
         - Backlog
-        - Done
+        - In progress
         action_id: projectBoard
       - type: octokit
         method: projects.createColumn
         project_id: '%actions.projectBoard.data.id%'
-        name: In Progress
+        name: Done
         owner: '%payload.repository.owner.login%'
         repo: '%payload.repository.name%'
-        action_id: ipColumn
+        action_id: doneColumn
       - type: octokit
         method: projects.createCard
         owner: '%payload.repository.owner.login%'
         repo: '%payload.repository.name%'
         content_id: '%actions.similarIssue.data.id%'
         content_type: Issue
-        column_id: '%actions.ipColumn.data.id%'
+        column_id: '%actions.doneColumn.data.id%'
       - type: createIssue
-        title: There's something similar here
+        title: Broken sidebar
         body: 01_the-similar-crosslink.md
       - type: closeIssue
         issue: Welcome
@@ -100,9 +111,19 @@ steps:
     link: '{{ repoUrl }}/issues/7'
     actions:
       - type: gate
-        left: '(8)'
-        operator: test
-        right: '%payload.comment.body%'
+        every: true
+        gates:
+          - left: '%payload.issue.title%'
+            operator: ===
+            right: Fix the sidebar
+          - left: '(8)'
+            operator: test
+            right: '%payload.comment.body%'
+        else:
+          - type: respond
+            with: e-unexpected.md
+            data:
+              expected: comment on the issue titled **Fix the sidebar** with the comment `#8`, the number of the similar issue
       - type: respond
         with: 02_find-commit.md
 
@@ -113,9 +134,19 @@ steps:
     link: '{{ repoUrl }}/issues/7'
     actions:
       - type: gate
-        left: '(312f87)'
-        operator: test
-        right: '%payload.comment.body%'
+        every: true
+        gates:
+          - left: '%payload.issue.title%'
+            operator: ===
+            right: Fix the sidebar
+          - left: '(312f87)'
+            operator: test
+            right: '%payload.comment.body%'
+        else:
+          - type: respond
+            with: e-unexpected.md
+            data:
+              expected: comment on the issue titled **Fix the sidebar** with the comment `312f872f79e50d505f02be5ddc97b3f7504d0189`, the SHA of the commit we're looking for
       - type: respond
         with: 03_context.md
         data:
@@ -133,36 +164,55 @@ steps:
         right: '%payload.project_card.content_url%'
         else:
         - type: respond
-          with: e-wrong-pr.md
+          with: e-unexpected.md
+          issue: Fix the sidebar
           data:
-            commit: 312f87
-          issue: Find the similar issue
+            expected: add pull request \#5 to the Done column of the v1.0.0 project
       - type: respond
         with: 04_find-broken-build.md
-        issue: Find the similar issue
+        issue: Fix the sidebar
 
 # Step 5:
   - title: Assign yourself
     description: Assign yourself to the pull request with a broken build
     event: pull_request.assigned
     link: '{{ repoUrl }}/issues/7'
     actions:
+      - type: gate
+        left: '%payload.pull_request.title%'
+        operator: ===
+        right: Add Git tips
+        else:
+          - type: respond
+            with: e-unexpected.md
+            data:
+              expected: 'assign yourself to the pull request titled **Add Git tips**'
       - type: respond
         with: 05_fix-build.md
 
 # Step 6: Something to do with tests
   - title: Fix the broken build
     description: Fix the broken build in the pull request with a new commit
-    event: push
+    event: pull_request.synchronize
     link: '{{ repoUrl }}/pull/6'
     actions:
       - type: getFileContents
         filename: docs/git-tips.md
         action_id: fileContents
       - type: gate
-        left: '(tricks)'
-        operator: test
-        right: '%actions.fileContents%'
+        every: true
+        gates:
+          - left: '%payload.pull_request.title%'
+            operator: ===
+            right: Add Git tips
+          - left: '(tricks)'
+            operator: test
+            right: '%actions.fileContents%'
+        else:
+          - type: respond
+            with: e-unexpected.md
+            data:
+              expected: edit `docs/git-tips.md` on the `add-git-tips` branch so that the word "tricks" is properly spelled
       - type: createStatus
         state: success
         sha: '%payload.head_commit.id%'
@@ -173,9 +223,21 @@ steps:
 # Step 7: Merge pull request
   - title: Merge
     description: Merge the final pull request
-    event: push
+    event: pull_request.closed
     link: '{{ repoUrl }}/pull/6'
     actions:
+      - type: gate
+        every: true
+        gates:
+          - left: '%payload.pull_request.merged%'
+          - left: '%payload.pull_request.title%'
+            operator: ===
+            right: Add Git tips
+        else:
+          - type: respond
+            with: e-unexpected.md
+            data:
+              expected: merge the pull request titled **Add Git tips**
       - type: createIssue
         title: Congratulations!
         body: 07_congratulations.md

responses/00_add-navigation.md

@@ -2,10 +2,12 @@
 
 This pull request introduces navigation to the documentation.
 
+_Note: in a step in this course, you'll be asked to perform the steps below. They're listed here for your convenience._
+
 ### :keyboard: Activity: Add to v1.0.0 project
 
 1. Click on **Projects** on the right side of this pull request.
 1. Choose the `v1.0.0` project from the list. You'll then see it's _Awaiting triage_
-1. Click on the project drop down, and place it into the **In Progress** column.
+1. Click on the project drop down, and place it into the **Done** column.
 
 I'll respond back in the original issue where you were asked to do this.

responses/00_existing-welcome.md

@@ -1,3 +1,3 @@
 # Welcome!
 
-Welcome to the course! We're going to walk through some strategies for dealing with large repositories. This is a similar issue to #1, but I'll let you decide if we should keep it or not.
+Welcome to the course! We're going to walk through some strategies for dealing with large repositories. This is a similar issue to #1. Please close this issue.

responses/00_welcome-issue.md

@@ -1,6 +1,6 @@
 # Welcome!
 
-Welcome to this Learning Lab course about working in large repositories. For example, you could be working in repositories with a lot of history. Or, working with many collaborators. No matter how your repository is "large", it's important to know how to navigate your workspace.
+Welcome to this Learning Lab course about finding your way through the history of GitHub repositories. For example, you could be working in repositories with a lot of history, many collaborators, or many files.
 
 Before you take this course, you may want to go through the [Introduction to GitHub](https://lab.github.com/githubtraining/introduction-to-github) course on Learning Lab.
 
@@ -12,7 +12,9 @@ In this course, you'll learn how to do lots of things, like:
 
 ### Cross-linking issues and pull requests
 
-GitHub has special capabilities to help reference other information on GitHub. For example, if someone references a GitHub issue or pull request from another issue or pull request, a link is created. At the same time, a cross-reference is created in the other issue. This two-way reference helps people track relationships of information across GitHub.
+GitHub has special capabilities to help reference other information on GitHub. For example, when you reference another issue or pull request by number, that number will be hyperlinked. At the same time, a cross-reference is created in the linked issue or pull request. This two-way reference helps people track the relationship of information across GitHub.
+
+![a screenshot of an issue linking to a PR, and a PR with a cross-reference to the issue](https://user-images.githubusercontent.com/16547949/67594663-d9710900-f732-11e9-8df8-d3173d952bd5.png)
 
 ## Step 1: Find an issue
 

responses/01_crosslink.md

@@ -2,7 +2,7 @@
 
 When you're working in a repository, you might want to find other issues or pull requests. Maybe someone has told you about a conversation, but they didn't send you a direct link. Or, maybe you remember an issue from the past but you don't know exactly where it is.
 
-Next, we'll practice finding issues and creating crosslinks to improve discoverability later.
+In this case, we want to see if there's another reference to the broken sidebar somewhere on this repository, and track down any work that's been attempted related to this. Let's see what we can find out!
 
 ### Finding issues and pull requests
 
@@ -19,5 +19,8 @@ When you want to create a crosslink, try typing the title of an issue or pull re
 ### :keyboard: Activity: Find and link to a related issue
 
 1. Please find the issue that is similar to this one
-   - This does _not_ mean that the issue is referenced, like in the last step - you should go look in the [Issues]({{ repoURL }}/issues) tab to find an issue with a similar title
-2. Comment in this issue with a reference to the related issue with a short description
+   - This does _not_ mean that the issue is referenced, like in the last step. This time, we're looking for a related issue that hasn't been connected to this one in any way.
+   - Try looking in the [Issues]({{ repoUrl }}/issues) tab to find an issue with a similar title to this one.
+2. Comment in this issue with a reference to the related issue and a short description, something along the lines of "this is a duplicate of issue #(number)".
+
+I'll respond when you comment on this issue.

responses/01_sidebar.md

@@ -0,0 +1,3 @@
+_Note: the content of this comment simulates common usage of issues as a way to request features of report bugs. Scroll down to the next comment in this issue for your instructions._
+
+There's no sidebar! Is this user error or is it actually missing?

responses/01_the-similar-crosslink.md

@@ -1,11 +1 @@
-# How to find issues and pull requests
-
-When you're working in a repository, you might want to find other issues or pull requests. Maybe someone has told you about a conversation, but they didn't send you a direct link. Or, maybe you remember an issue from the past but you don't know exactly where it is.
-
-### Finding conversations
-
-You can read all about the different ways to search in the [GitHub Help documentation](https://help.github.com/en/articles/searching-issues-and-pull-requests#search-by-open-or-closed-state).
-
-### Creating Links
-
-To learn about creating references, check out [GitHub's documentation](https://help.github.com/en/articles/autolinked-references-and-urls).
+I think this project would be better if it had a sidebar.

responses/02_find-commit.md

@@ -1,3 +1,5 @@
+Great job finding the duplicate issue! Feel free to close the other issue as a duplicate of this one, but I'll leave it up to you. Let's move on to finding out if these issues ever led to a sidebar being added to our project!
+
 # Finding commits
 
 An important part of version control is the ability to look into the past. By using `git blame`, and finding the story behind a commit, we're able to do more than _blame_ people for code. We're able to see the story around why a commit was made - what is the associated pull request? Who approved the pull request? What tests were run on that commit before it was merged?

responses/03_context.md

@@ -1,3 +1,5 @@
+Thanks for finding that commit! We now know that the sidebar was indeed added, and it was done in that commit. Let's see if we can dig a little deeper to find out if any planning or conversation occurred around this change. 
+
 # Context
 
 As we've already seen, conversations in issues and pull requests can reference other work.
@@ -27,17 +29,17 @@ When you're looking at a commit on GitHub, you can see a lot of information. Fro
 
 ## Step 4: Give more context
 
-In the story above, you might want to `@mention` the authors involved in the article. You may want to find them in person, or set up another way to collaborate. In this case, we want to collate the spread out information that you found through the commit.
+To help others find relevant context, we want to collate the information that you found in the prior steps.
 
 ![a screenshot of this issue with the projects section highlighted on the right, and a second screenshot of v1.0.0 project](https://user-images.githubusercontent.com/16547949/67590688-b0984600-f729-11e9-8d46-cc243d666331.png)
 
-You'll notice that this issue is part of [Project v1.0.0]({{ repoUrl }}/projects/1). Let's add the related pull request to the same project.
+One way we can do this, is by using [GitHub Projects](https://help.github.com/en/github/managing-your-work-on-github/about-project-boards). You'll notice that this issue is part of [Project v1.0.0]({{ repoUrl }}/projects/1), which tells us that the sidebar is part of the work related to our version 1.0.0 release. Let's add the related pull request to the same project so that the two artifacts can be tracked in tandem.
 
 ### :keyboard: Activity: Use a project to track related efforts
 
 1. Go back to {{ commitId }}.
 1. Click the link to the related pull request.
 1. In the pull request, click on **Projects** on the right side, and choose the `v1.0.0` project from the list.
-1. When the PR is added to the project, you'll see it's _Awaiting triage_, let's triage it! Click on the project drop down, and place it into the **In Progress** column.
+1. When the PR is added to the project, you'll see it's _Awaiting triage_, let's triage it! Click on the project drop down, and place it into the **Done** column.
 
-I'll respond in this issue when you've added the pull request to the In Progress column of the v1.0.0 project.
+I'll respond in this issue when you've added the pull request to the Done column of the v1.0.0 project.

responses/07_congratulations.md

@@ -2,7 +2,7 @@
 
 Great job! In this course, you've learned a lot about finding and sharing information. Within a GitHub repository, you can find history about what changes were made, and more importantly, _why_ changes were made.
 
-If you'd like to see this project on GitHub Pages, go to the [Settings tab]({{ repoURL }}/settings) of this repository and scroll down. Then, under **GitHub Pages**, select the **`master` branch `/docs` folder** as the source.
+If you'd like to see this project on GitHub Pages, go to the [Settings tab]({{ repoUrl }}/settings) of this repository and scroll down. Then, under **GitHub Pages**, select the **`master` branch `/docs` folder** as the source.
 
 Want to keep learning? Feel free to [check out our other courses]({{ host }}/courses).