Pull Request Follow-Along
Follow these instructions to practice making a contribution to a codebase!
Note
To complete this activity, make sure to have a local clone of a repository set up and ready to go. An instructor should make sure you have a repository for you or for your team's project.
If necessary, use this template to create a test repository for practice purposes. Simply click on the "Use this template" button, and once the new repository has been created, clone it.
The Template Repository
If using the hto-projects/gitflow-template
template repository, there are some ready-to-go issues. Each text file in the PullTestPoems folder has an error that must be fixed:
- 16BitIntel8088Chip.txt:
Koypro
should beKaypro
- ADreamWithinADream.txt: last line,
bean
should bedream
- Alone.txt:
alne
should bealone
- AMomentOfHappiness.txt:
birdos
should bebirds
- ARedRedRose.txt:
Boourns
should beBurns
- AutumnMovement.txt:
Sandberg
should beSandburg
- AWorldOfDew.txt:
strugle
should bestruggle
- ClenchedSoul.txt:
red
should beblue
- DontHesitate.txt:
thats
should bethat’s
- DustOfSnow.txt:
food
should bemood
- Harlem.txt:
Hughesy
should beHughes
- HopeIsTheThingWithFeathers:
woarm
should bewarm
- No1.txt:
Jhon
should beJohn
- Sick.txt:
byShel
should beby Shel
- Sonnet18.txt:
summer’s hay
should besummer’s day
- TheRedWheelbarrow.txt:
carlos
should beCarlos
- ThereWillComeSoftRains.txt:
tremolus
should betremulous
- TheTiger.txt:
🦁
should be🐯
- TheTyger.txt:
skis
should beskies
- TooManyDaves.txt:
Raves
should beDaves
- WeHaveNotLongToLove.txt:
Kentucky
should beTennessee
Each person should work on fixing one of these issues! Make sure if you're working on a team that each team member chooses a different file - this will help avoid merge conflicts and repeated work.
Fixing Your Issue - Branching & Pushing
The first step will be to make the changes to fix your assigned issue, and push them up to GitHub. The changes themselves do not matter much - they should be simple and trivial.
- Open Visual Studio Code, and open the local clone of the repository
- Create a new branch in the local repository using your name, e.g.,
amy-fix
- Command Line:
git checkout -b amy-fix
- VS Code: click branch name in lower left, enter
amy-fix
, select "+ Create new branch..." - Note: Be sure to name your branches well!
- Command Line:
- Open your file for editing (each person should have chosen their own file)
- Fix the error as listed above, and save the file
- View and stage your changes
- Command Line:
git add .
- VS Code: open Source Control pane, click on the changed file to see changes, click the "+" to stage them
- Command Line:
- Commit your changes with a message, e.g., "fix spelling"
- Command Line:
git commit -m "fix spelling"
- VS Code: in Source Control, enter "fix spelling" in the "Message" box, and click "Commit"
- Note: Be sure to enter clear commit messages!
- Command Line:
- Publish your branch
- Command Line:
git push --set-upstream origin amy-fix
- VS Code: in Source Control, click "Publish Branch"
- Command Line:
Once you've completed these steps, you should be able to take a look at your repository on the web at GitHub, and see your branch with the changes!
Making a Pull Request
The next step is to create a Pull Request to merge your branch (e.g., amy-fix
) into the develop
branch.
- Open up your repository on GitHub
- At the top, click on the "Pull requests" tab, and click the "New pull request" button
- Keep the base branch as
develop
- Set the compare branch to your branch (e.g.,
amy-fix
) - Click the "Create pull request" button
- Enter a detailed comment, and click the "Create pull request" button
Now your change should be ready to merge!
Merging the Pull Request
At this point, the team will discuss the proposed changes in the Pull Request. Typically, the develop
branch will be protected, so that it will only be possible to merge Pull Requests with an approval from another team member. Thus, this next part may require assistance from a fellow student.
It is typically bad practice to merge your own Pull Requests. It's always good to have someone else take a look at your work, give you feedback, and make sure everything is good to go.
- Find the "Reviewers" section on the right side of the Pull Request page
- Click the ⚙ icon
- Enter the GitHub account name of a team member
Now, it will be up to that team member to approve this request, and merge it into the codebase! The team member should:
- Go to the Pull Request Page
- If it is available, click the "Add your review" button
- Otherwise, click the "Files Changed" tab
- Take a look at the changes to the files - make sure they are all good!
- On the right side, click the "Review changes" button
- Enter a comment, (hopefully) select the "Approve" option, and click "Submit Review"
- Back on the Pull Request page, click the "Merge pull request" button
- Click the "Confirm merge" button
- Now the change has been merged! Last thing to do is delete the feature branch
And that's it! Hopefully by the end of this walkthrough, you were able to successfully make a contribution to a GitHub repository.