Exercise 6: Contribute to the book of somebody else

Exercise 6: Contribute to the book of somebody else#

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?

Tip

This part describes how you can make a change in the book of someone else.

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 - Issues - New issue. You did this in Exercise 4: Your Version of the Book.
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 Fork at the top right corner to create a copy of the repository under your GitHub account.
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>
Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_
Check the changes in the online book.
Go to the pull request page on your forked repository homepage (https://github.com/<your_username>/<your_friends_repo_name>/pulls) - and click New pull request.
On 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.
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.
Click Create pull request. On the next page you’ll see that the pull request is created in your friends repository.
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!

Tip

This part describes how you can accept the changes in your book made by someone else.

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. You can also find this by going to your repository and clicking on Pull requests.
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?
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.
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.
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.

Check your understanding

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?
What should you include in the description of a pull request?
How can you ensure that your friend is aware of your pull request?