diff --git a/config.yml b/config.yml index f7cd86a..1b0f899 100644 --- a/config.yml +++ b/config.yml @@ -12,31 +12,41 @@ before: - type: createIssue title: Welcome to this repository body: 00_existing-welcome.md -# - type: createPullRequest -# title: Create documentation structure -# body: 00_create-documentation-structure.md -# head: create-documentation-structure -# - type: mergePullRequest -# pullRequest: Create documentation structure -# - type: createPullRequest -# title: Add new pages -# body: 00_add-new-pages.md -# head: add-new-pages -# - type: mergePullRequest -# pullRequest: Add new pages -# - type: createPullRequest -# title: Add navigation -# body: 00_add-navigation.md -# head: add-navigation -# - type: mergePullRequest -# pullRequest: Add navigation -# - type: createPullRequest -# title: Add Git tips -# body: 00_add-git-tips.md -# head: add-git-tips -# - type: createStatus -# state: failure -# sha: 8a649c52d198e6ab0e80692bb660d08b299f479f + - type: createPullRequest + title: Create documentation structure + body: 00_create-documentation-structure.md + head: create-documentation-structure + - type: mergeBranch + head: create-documentation-structure + - type: deleteBranch + branch: create-documentation-structure + - type: createPullRequest + title: Add new pages + body: 00_add-new-pages.md + head: add-new-pages + - type: mergeBranch + head: add-new-pages + - type: deleteBranch + branch: add-new-pages + - type: createPullRequest + title: Add navigation + body: 00_add-navigation.md + head: add-navigation + - type: mergeBranch + head: add-navigation + - type: deleteBranch + branch: add-navigation + - type: createPullRequest + title: Add Git tips + body: 00_add-git-tips.md + head: add-git-tips + - type: createStatus + state: "failure" + failure: + description: >- + Please make sure that all words are spelled correctly. + sha: ab8fe26dfd24d863908a5074e704358023d11109 + context: failing-build steps: @@ -44,84 +54,98 @@ steps: - title: Close the linked issue description: Close the linked issue event: issues.closed - link: '{{ repoUrl }}' + link: '{{ repoUrl }}/issues/1' actions: - type: createIssue title: Find the similar issue body: 01_crosslink.md -# - type: createIssue -# title: There's something similar here -# body: 01_the-similar-crosslink.md -# - type: respond -# with: 01_next-step.md -# - type: respond -# with: 01_next-step.md -# issue: Welcome to this repository + - type: createIssue + title: There's something similar here + body: 01_the-similar-crosslink.md + - type: closeIssue + issue: Welcome + - type: respond + with: 01_next-step.md + - type: respond + with: 01_next-step.md + issue: Welcome # Step 2: Crosslink -# - title: Create a crosslink -# description: Find the relevant or duplicate issue or pull request, and create a contexual crosslink -# event: issue_comment.created -# link: '{{ repoUrl }}' -# actions: -# - type: gate -# left: '(6)' -# operator: test -# right: '%payload.comment.body%' -# - type: respond -# with: 02_find-commit.md + - title: Create a crosslink + description: Find the relevant or duplicate issue or pull request, and create a contexual crosslink + event: issue_comment.created + link: '{{ repoUrl }}/issues/7' + actions: + - type: gate + left: '(8)' + operator: test + right: '%payload.comment.body%' + - type: respond + with: 02_find-commit.md # Step 3: -# - title: Find a commit -# description: Find a specific commit (related to content concept of issue in step 2) -# event: issue_comment.created -# link: '{{ repoUrl }}' -# actions: -# - type: gate -# left: '(312f87)' -# operator: test -# right: '%payload.comment.body%' -# - type: respond -# with: 03_context.md + - title: Find a commit + description: Find a specific commit (related to content concept of issue in step 2) + event: issue_comment.created + link: '{{ repoUrl }}/issues/7' + actions: + - type: gate + left: '(312f87)' + operator: test + right: '%payload.comment.body%' + - type: respond + with: 03_context.md # Step 4: Finding info and context -# - title: Find context -# description: Mention the author in the pull request where commit was created -# event: issue_comment.created -# link: '{{ repoUrl }}' -# actions: -# - type: gate -# left: '(proper author)' -# operator: test -# right: '%payload.comment.body%' -# - type: gate (validate that the comment is in the proper pull request) -# left: 1 -# operator: test -# right: '%payload.issue.number%' -# - type: respond -# with: 04_find-broken-build.md + - title: Find context + description: Create a link to the pull request where the commit was created + event: issue_comment.created + link: '{{ repoUrl }}/issues/7' + actions: + - type: gate + left: '(5)' + operator: test + right: '%payload.comment.body%' + - type: respond + with: 04_find-broken-build.md # Step 5: -# - title: Assign yourself to the pr with broken build -# description: Assign yourself to the pr with broken build -# event: issues.assigned -# link: '{{ repoUrl }}' -# actions: -# - type: respond -# with: 05_fix-build.md + - title: Assign yourself to the pr with broken build + description: Assign yourself to the pr with broken build + event: pull_request.assigned + link: '{{ repoUrl }}/issues/7' + actions: + - type: respond + with: 05_fix-build.md # Step 6: Something to do with tests -# - title: Fix the broken build -# description: Fix the broken build -# event: push -# link: '{{ repoUrl }}' -# actions: -# - type: gate -# left: '(tricks)' -# operator: test -# right: '%payload.comment.body%' -# - type: createStatus -# state: success -# - type: createIssue -# title: Congratulations! -# body: 06_congratulations.md + - title: Fix the broken build + description: Fix the broken build + event: push + link: '{{ repoUrl }}/pull/6' + actions: + - type: getFileContents + filename: docs/git-tips.md + action_id: fileContents + - type: gate + left: '(tricks)' + operator: test + right: '%actions.fileContents%' + - type: createStatus + state: success + sha: '%payload.head_commit.id%' + - type: respond + with: 06_please-merge.md + issue: Add Git tips + +# Step 7: Merge pull request + - title: Merge the pull request + description: Merge the final pull request + event: push + link: '{{ repoUrl }}/pull/6' + actions: + - type: createIssue + title: Congratulations! + body: 07_congratulations.md + - type: respond + with: 07_final-issue.md \ No newline at end of file diff --git a/responses/00_add-git-tips.md b/responses/00_add-git-tips.md index 3764a08..b73ca3a 100644 --- a/responses/00_add-git-tips.md +++ b/responses/00_add-git-tips.md @@ -1,3 +1,5 @@ # Adding Git Tips -This pull request adds tips and tricks for using Git. \ No newline at end of file +This pull request adds a page to the documentation about tips and tricks for using Git. + +_Note: This is the pull request that you should assign yourself to in step 5._ \ No newline at end of file diff --git a/responses/00_add-navigation.md b/responses/00_add-navigation.md index e0f932e..a490fd8 100644 --- a/responses/00_add-navigation.md +++ b/responses/00_add-navigation.md @@ -1,3 +1,3 @@ # Add navigation -This pull request introduces navigation to the documentation \ No newline at end of file +This pull request introduces navigation to the documentation. diff --git a/responses/00_add-new-pages.md b/responses/00_add-new-pages.md index f8b44ab..d614d08 100644 --- a/responses/00_add-new-pages.md +++ b/responses/00_add-new-pages.md @@ -1,3 +1,3 @@ -# adding new pages +# Adding new pages -pull request for adding new pages \ No newline at end of file +This pull request introduces new pages to the documentation. \ No newline at end of file diff --git a/responses/00_create-documentation-structure.md b/responses/00_create-documentation-structure.md index 22ee3bd..d2e7401 100644 --- a/responses/00_create-documentation-structure.md +++ b/responses/00_create-documentation-structure.md @@ -1 +1,3 @@ -This is a pull request for introducing the documentation strucutre for docsify. \ No newline at end of file +# Documentation structure + +This pull request introduces the structure for the documentation. diff --git a/responses/00_existing-welcome.md b/responses/00_existing-welcome.md index 9219f3b..620c3dc 100644 --- a/responses/00_existing-welcome.md +++ b/responses/00_existing-welcome.md @@ -1,3 +1,3 @@ # Welcome! -(This is the issue that has duplicate information as the other welcome issue, and we will ask users to close this issue.) It's important that this issue references the other welcome issue, like #1 \ No newline at end of file +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. diff --git a/responses/00_welcome-issue.md b/responses/00_welcome-issue.md index f66557e..7e6828e 100644 --- a/responses/00_welcome-issue.md +++ b/responses/00_welcome-issue.md @@ -1,7 +1,25 @@ -# Welcome to this course! +# Welcome! -## Step 1: Find and close the crosslinked issue +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. -### :keyboard: Activity: +In this course, you'll learn how to do lots of things, like: -Find the issue that is crosslinked automatically from the instruction issue and close it because we don't need multiple threads with the same things. Maybe there's some info to bring over? Describing course goals really high level, and describing crosslinks between issues and pull requests \ No newline at end of file +- Find relevant issues and pull requests +- Search history to find context +- Make connections within GitHub to help others find things + +### 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. + +## Step 1: Find an issue + +Below, you will see a reference to another issue. The other issue references _this_ issue. The other issue appears to be a duplicate, so it would be a good idea to close it. + +### :keyboard: Activity: Find and close the cross-linked issue + +1. Find the other issue referenced from this issue +2. Close that issue + +
+

I will respond with your next steps in that issue.

\ No newline at end of file diff --git a/responses/01_crosslink.md b/responses/01_crosslink.md index a9f550e..fabe56c 100644 --- a/responses/01_crosslink.md +++ b/responses/01_crosslink.md @@ -1,9 +1,23 @@ # Finding relevant history -This is a new issue that has content similar to another issue. (or they could be pull requests). (In an existing issue that has a related issue or pull request buried somewhere) +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. -## Step 2: +Next, we'll practice finding issues and creating crosslinks to improve discoverability later. -## :keyboard: Activity: +### Finding issues and pull requests + +You can search for issues and pull requests in many ways, like by author, title, or even the most recently updated. You can also search closed issues. 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 references + +When you link to another issue, a reference within GitHub is automatically created. In fact, you don't even need to include the full link. If you were to type `#5` within a comment, that would turn into a link to issue or pull request number 5. + +When you want to create a crosslink, try typing the title of an issue or pull request directly after you type the `#` symbol. GitHub will suggest issues or pull requests that will link to the right place. To learn even more, check out [GitHub's documentation](https://help.github.com/en/articles/autolinked-references-and-urls). + +## Step 2: Create crosslinks + +## :keyboard: Activity: Find and link to a related issue + +1. Please find the related issue +2. Comment in this issue with a reference to the related issue with a short description -Please find the related issue and create a crosslink with a short description. Info about how to find issues and pull requests. \ No newline at end of file diff --git a/responses/01_next-step.md b/responses/01_next-step.md index bdd1464..0d0d6fc 100644 --- a/responses/01_next-step.md +++ b/responses/01_next-step.md @@ -1 +1 @@ -Your next steps can be found: \ No newline at end of file +[Your next steps can be found here]({{ repoUrl }}/issues/7). \ No newline at end of file diff --git a/responses/01_the-similar-crosslink.md b/responses/01_the-similar-crosslink.md index 1442cc5..d163940 100644 --- a/responses/01_the-similar-crosslink.md +++ b/responses/01_the-similar-crosslink.md @@ -1,3 +1,11 @@ -# The similar one +# How to find issues and pull requests -This is a similar issue to 01_crosslink.md and should be crosslinked. \ No newline at end of file +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). diff --git a/responses/02_find-commit.md b/responses/02_find-commit.md index d95e91a..b4b9a3f 100644 --- a/responses/02_find-commit.md +++ b/responses/02_find-commit.md @@ -1,9 +1,26 @@ # Finding commits -## Step 3: Find the commit +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? -### :keyboard: Activity: +The obvious reason to find things in history is to know about history. With issues and pull requests, we see a more complete story about history - not just the bare minimum. -Talk about git blame, and ask the user to find an author of a specific commit on `master`. Comment some part of the SHA or the link or something in the same issue issue. (at least the first 6 characters) +### What's `git blame`? -Find a commit where the navigation file was added. (`docs/_sidebar.md`) \ No newline at end of file +Git Blame is a Git functionality that shows what revision and author last modified each line of a file. Information like who made a commit, when, and even why can be found this way. If you aren't sure who introduced certain changes to a file, you can use `git blame` to find out. While `git blame` sounds rather accusatory, this can be used to understand the context around decisions. + +### What's a SHA? + +A SHA is a reference to a specific object. In this case, it's a reference to a commit. On GitHub, you can look at a specific commit to see the changes introduced, by whom, and if they were a part of a pull request. + +## Step 3: Find the commit + +### :keyboard: Activity: Find and reference the navigation commit + +1. Navigate to the [Code tab of this repository]({{ repoURL }}) + - _Tip: start this process in a new tab, since you will need it later_ +2. Click `docs` to navigate into the `/docs` directory +3. Click `_sidebar.md` to view the file +4. On the top right side of the file, click **Blame** to see the details of the most recent revision +5. Click the commit message, `add sidebar to documentation` to see the commit details +6. Copy some part of the SHA (at least the first 6 characters of the 40 character hexadecimal string listed after `commit`) +7. Comment (at least the first 6 characters of) the SHA in **this issue** diff --git a/responses/03_context.md b/responses/03_context.md index 9048ffa..79ce3db 100644 --- a/responses/03_context.md +++ b/responses/03_context.md @@ -1,7 +1,37 @@ # Context +As we've already seen, conversations in issues and pull requests can reference other work. + +But the amount of context goes much further than crosslinks - Remember, Git is version control! For example, the commit that you found in the last step is connected with much more information: + +- Who made the commit +- What other changes were included +- When the commit was made +- Which pull request the commit was a part of + +The pull request is important because it goes beyond knowing when a commit happened - you can know _why_ a commit happened. Finding history is not about _blaming_ anyone, but about seeing the bigger picture. Why were decisions made? Who was involved? What were the build outputs and test results for each commit? Who requested changes, and who approved them? + +### A story about finding experts + +Imagine you find an internal white-paper on a really exciting topic. You're looking for experts to help you research this topic for an upcoming project. When you find this article, you're ecstatic! But, there's no author referenced in the plain text. + +You can see that it's written in markdown, and it's versioned in GitHub. It's already a part of the `master` branch, but you want to know who was involved in creating this. You use `git blame` to see the author(s), and you can find the pull request associated with that branch. Now, you can see who all of the authors were, who the reviewers were, and if there are any other issues or conversations related to this topic. + +Just like that, you've found the people at your company who can help move your project forward. :tada: + +### Finding a pull request from a commit + +When you're looking at a commit on GitHub, you can see a lot of information. From this view, you can also find a link to the pull request in which the commit was created. We'll use this in the next step. + +![screenshot of a view of a commit on GitHub, highlighting the link to the pull request](/images/pr-link.png) + ## Step 4: Give more context -### :keyboard: Activity +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 bring the information that you found through the commit to the greater conversation. + +### :keyboard: Activity: Reference the related pull request in this issue + +1. In the tab where you found the commit SHA in the last step, click the link to the related pull request +2. Copy a reference (like a link) to this pull request +3. Comment with a link to the "Add Navigation" pull request in this issue -Can you please give some context about the commit? Or ping me in the pull request where it was created? Finding history is not about who screwed up, but really about the bigger picture. Why were decisions made? Who was involved, who requested it, who approved it, etc. diff --git a/responses/04_find-broken-build.md b/responses/04_find-broken-build.md index 826dfde..dac3ca2 100644 --- a/responses/04_find-broken-build.md +++ b/responses/04_find-broken-build.md @@ -1,7 +1,19 @@ -# Find the broken build +# More commit context -## Step 5: +Historical context of development includes references to other related work, like tests. + +### Real life examples + +If you'd like to see what this looks like in active repositories, take a look at [Electron](https://github.com/electron/electron/pulls) or [Visual Studio Code](https://github.com/microsoft/vscode/pulls). You can look through pull requests, see pull request statutes, and maybe even see the log outputs. + +## Step 5: Find the broken build + +There's an open pull request in this repository with a failing status. Before we fix it, let's find it! ### :keyboard: Activity: -Find the pull request with the failing build and assign yourself to it. \ No newline at end of file +1. In the [Pull requests tab]({{ repoUrl }}/pulls), find the pull request with the failing build +2. Using the **Assignees** section on the right side, assign yourself to the pull request + +
+

I will respond with your next steps in that pull request.

\ No newline at end of file diff --git a/responses/05_fix-build.md b/responses/05_fix-build.md index 619d383..dfcf89a 100644 --- a/responses/05_fix-build.md +++ b/responses/05_fix-build.md @@ -1,9 +1,13 @@ # Fix the build -Why does this matter in relation to the content of this course? +Now that you've seen that a status can be associated with a commit, let's fix this pull request up. The commit that you make will not only show the work you've done in history, but it will also show that you fixed the status as a part of a bigger picture. + +People in the future could look for this work and find out lots of things. They could find who made the fix, what the build status was before the fix, or who asked you to make the fix. This information is created automatically, without any extra work from the developer. ## Step 6: Fix the build -### :keyboard: Activity: +### :keyboard: Activity: Correct the spelling to fix the build -Instructions to fix the build \ No newline at end of file +1. [Edit the `docs/git-tips.md` file]({{ repoUrl }}/edit/add-git-tips/docs/git-tips.md) on this `add-git-tips` branch +2. Correct the spelling of the word `trics`, by changing it into `tricks` +3. Commit the changes \ No newline at end of file diff --git a/responses/06_congratulations.md b/responses/06_congratulations.md deleted file mode 100644 index d2390cb..0000000 --- a/responses/06_congratulations.md +++ /dev/null @@ -1,3 +0,0 @@ -# YOU DID IT! - -Here's how to enable GitHub Pages so you can actually see this project \ No newline at end of file diff --git a/responses/06_please-merge.md b/responses/06_please-merge.md new file mode 100644 index 0000000..be81915 --- /dev/null +++ b/responses/06_please-merge.md @@ -0,0 +1,6 @@ +## Step 6: Merge + +### :keyboard: Activity: Merge this pull request + +1. Merge this pull request +2. Delete the branch \ No newline at end of file diff --git a/responses/07_congratulations.md b/responses/07_congratulations.md new file mode 100644 index 0000000..e1a82c5 --- /dev/null +++ b/responses/07_congratulations.md @@ -0,0 +1,10 @@ +# Congratulations! + +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. + +Want to keep learning? Feel free to [check out our other courses]({{ host }}/courses). + +
+

I won't respond to this issue, just close it when you are done!

\ No newline at end of file diff --git a/responses/07_final-issue.md b/responses/07_final-issue.md new file mode 100644 index 0000000..9080935 --- /dev/null +++ b/responses/07_final-issue.md @@ -0,0 +1 @@ +Great job! Find your [final issue here]({{ repoUrl }}/issues/9). \ No newline at end of file diff --git a/responses/images/pr-link.png b/responses/images/pr-link.png new file mode 100644 index 0000000..3185058 Binary files /dev/null and b/responses/images/pr-link.png differ