Excercise 6

book/exercises/006.md

@@ -1,26 +1,48 @@
 # Exercise 6: Contribute to the book of somebody else
 
-So far you did everything on your own. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using git! Therefore, you'll take the book of someone else and create your own version of that one. Unlike before, we cannot simply make a branch, because you don't have access to their repository. However, you can make a copy of the repository on your own account, which is called a fork. Let's use that and contribute back to your friend's repository at the end.
+```{tip}
+For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner.
+```
+
+So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**.
+
+```{note}
+The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository.
+```
 
 > Can you fork a book repository of someone else, make changes and contribute back?
 
-1. Go to the repository you want to contribute to (`https://github.com/<your_friends_username>/<your_friends_repo_name>`) and add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md).
-2. Go back to the home page of repository you want to contribute to (`https://github.com/<your_friends_username>/<your_friends_repo_name>`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account.
+```{tip}
+This part describes how you can make a change in the book of someone else.
+```
+
+1. Go to the repository to which you want to contribute (`https://github.com/<your_friends_username>/<your_friends_repo_name>`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md).
+2. Go back to the home page of repository to which you want to contribute (`https://github.com/<your_friends_username>/<your_friends_repo_name>`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account.
 3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from <your_friends_username>/<your_friends_repo_name>`
-4. Make some changes on the main branch of your forked repo.
+4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_
 5. Check the changes in the online book.
 6. Go to the pull request page on your forked repository homepage (`https://github.com/<your_username>/<your_friends_repo_name>/pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`.
 7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: <your_username>/<your_friends_repo_name>:compare: main` into the original repository `base repository: <your_friends_username>/<your_friends_repo_name> base:main`. This should be the case by default.
 8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #<number_of_issue_created_in_step_1>` so that the pull request is linked to the issue.
 9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository.
 10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away!
 
-#### ROBERT, CAN YOU CONTINUE HERE?
+```{tip}
+This part describes how you can accept the changes in your book made by someone else.
+```
+
+1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`.
+2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository?
+3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`<your friend>` wants to merge x commit(s) into `<your_username>`:`main` from `<your_friends_username>`:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork.
+4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes.
+5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there.
+
+Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. 
 
 ```{admonition} Check your understanding
 :class: note
 
-Before moving on to the next exercise, make sure you understand the following:
+Before moving on, make sure you understand the following:
 - What is a fork and how does it differ from a branch?
 - Why is it important to create an issue before starting to work on a contribution?
 - How do you create a pull request from a forked repository to the original repository?