In the previous step, Activity: Use the GitHub Desktop Client, you used Github Desktop to manage the workflow of committing files, branching, and merging. In this tutorial, you’ll do a similar activity but using the browser-based interface that Github provides rather than using a terminal or Github Desktop.
Understanding the pull request workflow is important for reviewing changes in a collaborative project, such as an open-source project with many contributors. Using GitHub’s interface is also handy if you have non-technical reviewers.
By default, your new repository has one branch called “Master.” Usually when you’re making changes or reviews/edits, you create a new branch and make all the changes in the branch. Then when finished, the repo owner merges edits from the branch into the master through a “pull request.”
Although you can perform these operations using Git commands from your terminal, you can also perform the actions through the browser interface. This might be helpful if you have less technical people making edits to your content.
To make edits in a separate branch on GitHub:
Pretend you’re a SME reviewer. Go to the Github repo and create a new branch by selecting the branch drop-down menu and typing a new branch name, such as “sme-review.” Then press your Enter key.
When you create a new branch, the content from the master (or whatever branch you’re currently viewing) is copied over into the new branch. The branch is like doing a “Save as” with an existing document.
Click a file, and then click the pencil icon (“Edit this file”) to edit the file.
Make some changes to the content, and then scroll down and click Commit Changes. Explain the reason for the changes and commit the changes to your sme review branch by clicking Commit Changes.
Reviewers could continue making edits this way until they have finished reviewing all of the documentation. All of the changes are made on a branch, not the master.
Now that the review process is complete, it’s time to merge the branch into the master. You merge the branch into the master through a pull request. Any “collaborator” on the team with write access can initiate and complete the pull request. You can add collaborators through Settings > Collaborators.
To create a pull request:
Click the New pull request button.
Select the branch (“sme review”) that you want to compare against the master.
When you compare the branch against the master, you can see a list of all the changes. You can view the changes through two viewing modes: Unified or Split (these are tabs shown on the right of the content). Unified shows the edits together in the same content area, whereas split shows the two files side by side.
Now pretend you are the project owner, and you see that you received a new pull request. You want to process the pull request and merge the sme review branch into the master.
Click the pull request and view the changes by clicking the Files changed tab.
If you only want to implement some of the edits, go into the sme review branch and make the updates before processing the pull request. The pull request doesn’t give you a line-by-line option about which changes you want to accept or reject (like in Microsoft Word’s Track Changes). Merging pull requests is an all-or-nothing process. You can also click Review changes and select the Request changes option, asking the reviewer to make the changes.
Note also that if the pull request is made against an older version of the master, such that the master’s original content no longer exists or has moved elsewhere, the merges will be more difficult to make.
Click Confirm merge.
The sme review branch gets merged into the master. Now the master and the sme review branch are the same.
Click the Delete branch button to delete the sme review branch.
If you don’t want to delete the branch here, you can always remove old branches by clicking the branches link while viewing your Github repository, and then click the Delete (trash can) button next to the branch.
If you look at your list of branches, you’ll see that the deleted branch no longer appears.
You might need to add collaborators to your Github project so they can commit edits to a branch. If other project members aren’t collaborators and they want to make edits, they will receive an error. (See Inviting collaborators to a personal repository.)
If people don’t have write access, they can fork the repo instead of making edits on a branch on the same project. Forking a project clones the entire repository, though, rather than creating a branch within the same repository. The fork (copy) then exists in the user’s personal GitHub account. You can merge a forked repository (this is the typical model for open-source projects with many outside contributors), but this scenario probably is less common for technical writers working with developers on the same projects.
To add collaborators to your Github project:
Click Add Collaborator.
53/94 pages complete. Only 41 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson