GitHub Collaboration – a Partner Exercise

If you’re new to GitHub and are looking for a step-by-step guide on collaboration, this Exercise is for you!

With this exercise, you and another GitHubber (or two or three …) will write a story together. No code. Just a simple, written story in the language of your choice.

One GitHub user will create a GitHub repository containing the start of a story. Each collaborator will, in turn, build on that story. Who knows what characters will appear? What plots will develop?!

Pre-Requisites

• A GitHub account
• Internet access

All tasks in this Exercise are done using GitHub. Installing git on your local computer is not required.

Collaboration Summary

If you have a collaboration partner(s) already, great! One of you (the Host) will create a repository containing the story (Step 1). Other partners (the Guests) will be collaborators (Step 2). The Host will then manage updates made by the Guests (Step 3).

If you do not have a partner (yet), I recommend either performing the steps as the Host then inviting GitHub users to be the Guest, or be my Guest on: https://github.com/leaherb/story-build.

Tip: Open another Internet browser window or tab so you can follow this Exercise lab while you use GitHub.

Step 1 (Host) Start the Story

Create a repository called story-build to start the story:

Create a new repository

1. Log into GitHub. See the plus sign () in the upper-right corner next to your avatar (or identicon)? Click it, then select New repository.
   

2. Name your repository story-build.
3. Add a short, clear Description.
4. Select Initialize this repository with a README.
   

   

5. Click Create repository button.

Start writing a story

1. With the story-build repository open, click Create new file button (near the middle of the page).
2. Name the new file, for example story.md. (The .md extension defines it as a Markdown file type, making it easier to edit and read on GitHub than a simple text file.)
3. Choose Soft wrap (instead of No Wrap, from the right-most pull-down) so it’s easier to edit your new file.
4. Start a story. Add the first few sentences of a new story. Consider ending with a hook word or phrase to help the imagination of your collaborators (example: ‘Suddenly …’.)
5. Click Preview tab to see what your file will look like. If you want to make updates, simply click back to <> Edit new file.
6. Commit. Scroll to the commit section at page bottom. In the first field, add a commit statement, for example Start the story. Click Commit new file. button.
   

7. Link. If you are collaborating with another GitHub user, give them the link to your new repository.

Step 2 (Guest) Add to the story

To update someone else’s repository, you create a Fork. Then offer your updates in the form of a Pull Request. Don’t worry right now if are unfamiliar with these terms, you’re about to see them in action!

Create a fork

1. Open repository. Ask the Host to send you the link.
2. Open story. Click story.md from the list of files.
3. Edit. Click the pencil icon above the edit box on the right ().
4. Notice a message saying you don’t have write access to the file. That’s ok. When you make updates to the file, GitHub will automatically create what is called a Fork.

Edit the story

5. Add to the story. Make your updates in the <>Edit file box. Consider making an interesting twist to the plot. End with an intriguing word or phrase the next contributor can use to spark their imagination.
6. Preview. Click Preview changes tab to view your contribution.

Make Pull Request

7. Propose file change. When happy with your updates, scroll to the bottom of the page. Enter a short description (‘commit statement’) of your change, then click Propose file change button.
8. Click Create pull request button. You’ll be taken to a page to review the changes you’ve made. Write a note to your Host about the change you are proposing. Then, click the Create pull request button.

9. Review. Now if you go to the repository’s page then the Pull requests tab, you’ll see your request! It’s now up to the Host to merge your changes with the master version of the story.

Step 3 (Host) Merge request

You’re almost done! Now, merge the changes made by Guest.

1. Repository. Go to, or refresh, your repository’s page.
2. View Pull requests. From the menu bar, choose Pull requests.
3. Open Pull request. Click the title of the Pull request you want to merge.
4. Click Files changed to see what the pull request changes.
5. Click Review changes button. In the pop-up, write a comment to the Guest contributor. Check the Approve radio button, indicating that the Pull request/merge is allowed to go forward.
6. Click Submit review button
7. Final approval. If all is well, you’ll see a message that there are no conflicts. Click Merge pull request button, then Confirm merge button.
   

Done!

When you view story.md from the Host‘s repository, you’ll see the Guest‘s changes! Good job.

Please leave a comment if you found this Exercise helpful, or found an error. Thank you!