Connect the Dots in a GitHub Repository

Step 1: Resolve Duplicate Issues

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.

With collaboraration from multiple team members, sometimes issues can be duplicated. In the above example, the new issue #8346 is a duplicate of a previous issue #8249. The cross-reference ability allows you to track these duplications and close issues when appropriate.

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, start 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 the Autolinked References and URLs article.

⌨️ Activity: Find and close the cross-linked issue

Navigate to the issue #1 (Welcome)
Type "Duplicate of #2" as a comment and close issue #1

Step 2: Find a commit in history

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?

The obvious reason to find things in history is to know about the history. With issues and pull requests, we see a more complete story about about the history, not just just the bare minimum.

What's `git blame`?

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 Secure Hash Algorithm (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.

⌨️ Activity: Find commit in history

Navigate to the Code tab of your repository
- Tip: you may have previously created your repository in a new tab
Click docs to navigate into the /docs directory
Click _sidebar.md to view the file
On the top right side of the file, click Blame to see the details of the most recent revision
Click the commit message, add sidebar to documentation to see the commit details
Copy the first seven characters of the SHA (the first 7 characters of the 40 character hexadecimal string listed after commit)
Comment on issue #2 by adding the SHA from step 6 as a comment text and click on "Comment" button

Step 3: Fix a broken sidebar

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, using comments, occurred around this change.

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 such as:

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?

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.

⌨️ Activity: Fix a broken sidebar

In the main branch Edit the docs/_sidebar.md file.
Correct the spelling of the reference (doc-references__.md) on line 4 by changing it into (doc-references.md).
Select or create a new branch fix-sidebar for this commit and start a pull request.
In the Pull requests tab, create a pull request by comparing 'main' branch to 'fix-sidebar' branch.
Using the Assignees section on the right side, assign yourself to the pull request.
In the PR comment add 'Closes #2' and autolink issue #2.
Merge this pull request.
Delete the branch 'fix-sidebar'.

Finish

Congratulations friend, you've completed this course!

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.

What's next?

Check out these resources to learn more or get involved:

Are you a student? Check out the Student Developer Pack.
Take another GitHub Skills course.
Read the GitHub Getting Started docs.
To find projects to contribute to, check out GitHub Explore.

Get help: Post in our discussion board • Review the GitHub status page

Tvkqd/connect-the-dots