Get the Most from GitHub on Your Personal Project

Photo by Markus Spiske on Unsplash

Having a few personal projects available for the public to see can add to any resume, from students look for their first internship to experienced developers. Even a small utility can impress potential interviewers if you go above and beyond with your process. Personally, a well executed GitHub project is more valuable to see than thousands of lines of modern code. You will always have to adapt to a new codebase at a job, but the skills demonstrated by using branches, pull requests, issues and more can leave a lasting impression.

Start With a Fresh Repository

Coming up with an idea is always the hardest part, so let’s skip that part. Once you know what you’re making, the first step is to create a fresh repository. GitHub offers you some great advice right off the bat on the new repo page:

Great repository names are short and memorable.

When using multiple words in a repo name, I prefer to use kebab-case, but you should live your dream.

Additionally, checking the box to initialize your repo with a Readme will make getting started easier. Once your repo is created, you’ll be faced with its GitHub page and the contents of your new Readme. Copy your repo’s path from the “Clone or Download” button, and copy it into your local machine. You may have a workspace folder, or a GitHub folder, so open your favourite terminal and cd to that folder. To get your local machine connected to your GitHub repo, clone from GitHub:

git clone git@github.com:your-user/your-repo.git
cd your-repo

Plan Your Project

The hardest part of executing this project will likely be this step. Breaking down a big picture into goals with smaller tasks is an art that takes years to perfect. It’s not super important to plan the entire thing right away, but having an idea of how to get started will be more than enough to actually start writing some code.

One simple place to start is getting an environment and some form of Hello World setup. Before you break open your favourite editor, create a new GitHub issue. This is where you can keep track of your individual tasks and add some options for organization. GitHub provides some default labels, but you can customize them with fun colours and emojis to show a bit more personality. You can even assign yourself, to see your avatar throughout your history later.

Give your issues descriptive titles and try to fill out some key info each time you create one. Some simple headings you can start with are:

1. Description — what are you going to solve in this issue?
2. Acceptance Criteria — what results will make you consider this issue done?
3. User persona — explaining why a feature is required and by whom shows an understanding of the software development process very rarely found in personal projects. Even if it’s as simple as “a user of my utility class will be able to save time and effort with this function.”

Start Working on a Branch

Each bit of code you write should be done on a branch, just like at a normal (hopefully) software job. First, let’s talk naming conventions. I like to stick to kebab case again, starting with the issue number, and a few words describing the branch’s purpose. For instance:

git checkout -b 1-hello-world

This will create a new branch (that’s where the -b comes in) referencing your first issue!

When you are ready to save your progress in a commit, you will need to eventually push your local changes up to GitHub. The first push will need to be upstream, like this:

git push -u origin 1-hello-world

Every time after that, a simple git push will suffice.

Creating a Pull Request

Once you’re done with your code for the issue you created, you’re ready to create a pull request. This is where you can take a look at your changes and make sure the difference in code (or diff for short) is what you expect. If you were working on a team, this is where you can assign reviewers and have other members comment on your code.

If you’ve recently made changes to a branch, GitHub may offer you a prompt to create a pull request. Either way, you can select the pull request tab (next to issues) and create it that way. For a solo personal project, most of your pull requests will be compared against and then merged into the master branch. In that case, you will see base: master <- compare: 1-hello-world for example.

When you’re ready to merge, you can edit the message to include a fun feature of GitHub: automatically closing your issues. If your pull request is tied to issue #1, you can simply write Fixes #1 and GitHub will do the rest.

Talk About Your Process

Once you have a functional project finished, you may have dozens of closed issues and pull requests publicly available. You can even have some open issues, showing that you are still working. In your project’s Readme, make sure to include a link to your Issues page and encourage viewers to open an issue. On your resume, make sure to refer to following a more advanced GitHub flow than simply cloning and tracking code.

A successful software developer wears many non-coding related hats throughout their career, and showing a bit of process off in your personal projects can really set you apart.

Next time we’ll talk about tagging releases, milestones and the projects tab!