Making My First Pull Request on GitHub

Making My First Contributions

My first thought of contributing to an open source project began when I first started using Hugo. Having added extra features and making improvements to the theme base code (Anubis2), I realised some of them can be a PR (pull request) so the rest of the users of the theme can benefit. I never got round to doing it as it seemed a bit daunting as a Git newbie.

What Prompted Me

Two things triggered my desire to take the first step in creating PRs:

• The friendliness and encouragement from Junyi, the theme’s dev/creator, who suggested that I make my first PR for the fixes I made in the RSS.xml template.
• One of my Mastodon followers, @Minty95, has shared with me a problem he’s had with ReText’s syntax highlighting of fenced code blocks. I managed to fix the bug and really want to share it with other users of this app. It’s more complex than the Hugo theme changes, so I’m still working on it…

Merge Success

After reading the basic procedures and best practices, it didn’t seem too bad; so I tried out a few PRs with the hugo-theme-anubis2 project and I am happy to say, all three PRs I submitted were merged with the project’s main branch! 🥳

I’m especially pleased with the RSS validation fix because the before and after is significant.

Creating a Pull Request: Step-by-Step Guide

Here’s my simple notes of what I did to create my first pull request on GitHub.com. Hope after this short tutorial, you will find it less intimidating to contribute to projects you like! I will assume you have some basic knowledge about Git and using Terminal commands.

Initial Repository Setup

• Fork (duplicate) a project/repository into your own GitHub account by going to the project’s repository page and click the “Fork” button.

• Clone (download) a copy of the forked project onto your local machine using the remote URL (HTTPS or SSH)¹: git clone <remoteURL>

• Once the project is downloaded onto your local machine, open it in an IDE like VSCodium (my personal preference) and open a Terminal window. cd into the newly cloned repo.

• To sync remote changes from the original project’s repo onto the local fork, we configure an upstream remote for the original repo (AKA upstream).

  • Copy the original project’s remoteURL

  • Check the current remote with git remote -v, it will show something like this:

  1> git remote -v
  2origin <git@github.com>:your-username/projectname.git (fetch)
  3origin <git@github.com>:your-username/projectname.git (push)

  • Add upstream remote:
    git remote add upstream git@github.com:some-developer/projectname.git

  • Check remote again with git remote -v. The origin should point to the fork, and upstream should point to the original repo.

  1> git remote -v
  2origin git@github.com:your-username/projectname.git (fetch)
  3origin git@github.com:your-username/projectname.git (push)
  4upstream git@github.com:some-developer/projectname.git (fetch)
  5upstream git@github.com:some-developer/projectname.git (push)

• To sync your fork, we need to fetch(download) the latest changes from the upstream repo

  • First make sure you’re on the master(sometimes called main) branch:

    git checkout master

  • Fetch updates from the remote (on GitHub.com) project’s repo:

    git fetch upstream

  • Merge(combine) the changes from the upstream repo into the local repo:

    git merge upstream/master

Work On a Local Forked Branch

• This is the setup portion done! The local forked repo can now be updated as required. We can start working on our contribution, suggestion, new feature, bug fix, etc. To do this we must create a new branch.

  • Check what branch we’re currently on: git branch

  • Create a new branch with a descriptive and meaningful name, describing what your proposed change will do, e.g. NewFeature: git checkout -b NewFeature

  • Make the changes. Once completed, stage the changes and add commit messages:
    git add . and git commit -m "Add new feature."

  • Now push the changes in the NewFeature branch back into your forked repo on GitHub.com.
    git push -u origin NewFeature²

  Tip

  If you want to automatically set the upstream on pushes of new branches, use global Git config setting: git config --global push.autoSetupRemote true

Actual Pull Request

• Finally, go back to GitHub.com to check the pushed changes in your forked repo. There will be a banner near the top notifying us of the recent new branch being pushed. Click “Compare & pull request”.

• On the “Comparing changes” page, there is a small bar at the top, with a left pointing arrow in the middle, if not click “compare across forks”.

  • The right of the arrow is the head, which is the NewFeature branch in your forked repo that you just pushed.
  • The left of the arrow is the base, which is the original project’s main/master branch.

  

  • Fill in the title and description of your changes. You can see the diff view (differences between the old and new files) at the bottom of the page. Click “Create pull request” once you’re satisfied with the changes.

  

• Wait patiently for the devs to review your code, discuss and revise when necessary with the maintainers. If changes are required, just do the work locally, commit them, and push it to your fork. The PR will update itself.

• Each project has their own rules or guidelines for making PRs, so check if there’s a CONTRIBUTING.md before creating one for a smooth experience.

Maintenance Tips

• It is good practice to delete branches that have successfully merged with the base repo, and the PR completed. This helps reduce confusion, keeps things tidy, and prevents us from working on old branches accidentally.

  • To delete a local branch, make sure you’re not actively on that branch; therefore, switch to a branch like master/main: git checkout master

  • Delete the finished/completed/merged branch with: git branch -d <branch-name>

  • If you prefer the GUI method you can “View all branches” and delete your branches in the list view.

  

  

• If for some reason, you have no future contribution plans to a project, you can consider deleting the fork off your GitHub repo. This is especially if it is consuming your GitHub resources (e.g. Action minutes, storage, etc).

• If you are planning on future contributions though, you can always archive the fork. This makes it read-only so it doesn’t consume resources. Go to the repo’s settings and find the “Archive this repository”.

Conclusion

Congrats, you have gone through how to make a pull request! If you’re like me, a newbie to all this, I genuinely hope you feel more confident to creating a PR for your favourite projects. I have now submitted four—but probably have another few to add to my current Hugo theme’s repo (Anubis2). Hopefully the more complex PR with the ReText syntax highlighting bug will go smoothly too. 🤞