Chapter 3 Introduction to Github

3.1 Session aims

  • Navigating GitHub
  • Comparing code changes across different versions and branches
  • Creating a branch on GitHub
  • Issues and pull requests
  • How to use GitHub to check or conduct code reviews
  • The basics of Github good practice

Definitions you’ll need in this chapter

Repository: A repository (or “repo”) is a place where you can store and manage your code or any other files. It is a folder that holds all the files relevant to your project, but also contains the version history and information related to a project. There are two different types of repositories: local repositories which are personal to you and on your local computer, and remote repositories which are on Github and shared with others.

Push: Sending your committed changes from your local repository to a remote repository on Github, making them accessible to others collaborating on the same project.

Pull: Fetching changes from a remote repository on Github and merging them into your local repository. It retrieves any new work done by others and incorporates those changes into your local copy.

3.3 Comparing code changes

As mentioned in the previous section, the landing page for each repository shows an overview of the code contained in that repository. For each file, the overview shows the last commit made for each file in that branch, including the time and the commit message.

This is useful to see the last change made by file, and you can then click on each of the commit messages to see further detail on each commit, including the changes made to each file. However, you can actually see much more detail than this by looking at the commit history.

3.3.1 Viewing all previous commits

You can view the commit history of any branch by clicking on the clock icon directly under the green code button. This also tells you how many commits have been made on this branch in total.

The commits page that this takes you to shows a full list of all commits on this branch in reverse chronological order (with the latest commit on top). Hover over the image below to see all of the relevant parts of this page:

Your Image 5 Branch Filter Date files sha browse

  • Change branch: This drop-down menu shows you which branch you’re currently viewing commits for. To swap branches, select a new branch from the drop-down list.

  • Filter commits: If you’re trying to find a specific commit (good commit messages help with this!) you can narrow it down here. These drop-down menus allow you to filter commits by the user who made them or (less usefully) the date they were made.

  • Date of commit: As mentioned, commits are arranged by date of commit. They are grouped by date, and you can see the date at the top of each grouping.

  • Commit details: In this list, you can see the high-level details for each commit. At a glance you can see the commit message, the date the commit was made, and who made it. Clicking on the commit message here takes you into further details of each commit (e.g. the line-by-line changes), which we’ll talk about in the next section.

  • Copy SHA: Each commit is associated with a unique number, known as an SHA. Clicking here allows you to copy the SHA, which you can use to revert back to or share a specific snapshot of the code with others.

  • Browse commit: Clicking here allows you to browse the repository as it looked at the time of this specific commit. This has pros and cons over viewing the commit itself; you won’t be able to see exactly what changed as part of this commit easily, but you will be able to view the entire codebase clearly.

If you click on any one of the commit messages in the above list, it will drill down even further into the commit itself, allowing you to see more details about what change was made at the time. Hover over the image below to see all of the details:

Your Image 6 Commit Changes Lines

  • At the top, you’ll find the commit details. This provides basic details such as the commit message, who made the commit and what time they did so, as well as any tags and pull requests the commit is associated with.

  • On the line below, you will see a high level summary of the number of changes made as part of the commit. This lets you know how many files have changed overall, as well as how many lines of code have been added and how many lines have been removed. Any lines of code which have been edited will show up as one line added and one line removed.

  • Below this, there’s a line-by-line breakdown of the changes. This shows each file containing changes one by one, with an indicator bar at the top giving the name of the file and a rough idea of the split of additions and changes in that file (indicated by red and green squares). Below this, you can see the changes in context. The screen is split in half, with the code prior to the commit on the left, and the code after the commit changes have been made on the right. Additions are highlighted in green, and removals in red. Therefore, a line of code that has been edited will be highlighted in red on the left, and green on the right.

3.3.2 Tasks

15:00

  • Remaining on the same repository, change to the bugfix/vba_code branch
  • How many commits does that branch have in total?*
  • View all of the commits in chronological order, when was the most recent one done?
  • Select the most recent commit and look at the changes made in this commit. How many lines of code were added and how many were removed?
  • Find an example of a useful commit message; can you understand what that change was?

3.4 A Github workflow

Throughout the rest of this session, I’m going to demonstrate Github features in a logical order, following a typical Github workflow. This goes as follows:

Imagine you work in a team that stores and maintains all of its code on Github. One day, you spot a problem with your code…

  • You use the issues to create a ticket relating to the issue, to let other people (current collaborators or future auditors) know what the problem is.

  • You create a new branch relevant to the issue you’re going to fix, and you write code that fixes the issue in that branch.

  • You make a pull request to show that you want to merge the code from your new branch back into the live code.

  • A code review is conducted to check that the code you’ve written works, is sensible, and doesn’t break any other functionality.

This is a standard workflow for pretty much any repository, and one you’ll probably use all the time when you’re up and running with Github! We’ll run through these steps one by one in the next sections.

3.5 Raising issues

3.5.1 How do issues work?

Raising an issue is usually the first step when you want to change something within your code, and they represent a quick and easy way to record problems and planned changes in your code. Issue tickets can be raised in Github, and are stored permanently alongside your code (even after you’ve completed and closed it). This is great for auditability purposes and for retaining a permanent record of the changes you’ve made to your code; you’ll always understand how the problem was identified, who spotted it, and the kinds of problems it caused.

There are a number of features and actions you can take with issues, including:

  • People working on that issue can be assigned to it
  • Conversations can take place directly on the issue log
  • When changes are complete, they can be linked to the issue so you can see how it was resolved.

All of which make issues a great way to record and track changes made to your code.

Anyone with access to your repository can record issues or respond to comments on issues they raised, but only people with write or admin access can actually action those issues or assign them to people.

3.5.2 Viewing issues

Clicking on the “issues” tab at the top of your repository takes you to the issues overview page. Here, you can see a summary of all of the issues associated with your repository. Hover over the image below to see the different information available on this page:

Your Image 6 Search Open New Issues Details

  • Search your issues: As default when you land on this page, it will show you all open issues, arranged in chronological order. You can also search to find a particular issue you’re looking for, searching by issue number, key words in the description, or using the Github search syntax to filter on date or issue author.

  • Open and resolved issues: As mentioned, by default Github will only show you open issues on your repository. However, even when issues are closed they don’t disappear, and you can change the view in this section to allow you to look back through closed issues.

  • Raise a new issue: Click this green button to start the process of raising a new issue (covered in the next section).

  • List of issues: This is the list of the issues shown for your repository. The appearance is very similar to commits, you can see the issue name, when it was raised, and who raised it. Clicking on the issue title takes you into the individual page for that issue, which provides further information.

  • Issue details: Details about the issue are shown on the right hand side of the list. This includes labels (you can tag your issue as needing help, or paused for now), who is assigned to be fixing the issue, milestones (which shows if there is a pull request linked to the issue), and number of comments on this issue thread. This gives you a good overview of what is going on with this issue (is it in progress? Is someone working on it? Is there a lot of discussion going on about it?), and you can also sort the issue order on any one of these details.

Clicking on any one of the issue titles takes you into the overview for this issue:

Here, you can see the further details that the user provided when they submitted the issue; this is done by completing a template (which you’ll see in the next section). This is also where you as the developer interact with that issue. On the right hand side, you can use the cog next to the “assignees” section to assign people who will be working to fix the issue. A “bug” or “enhancement” label is added by default when you complete the template, but you can also add additional labels to indicate if an issue is a duplicate, out of scope for the project, requires help, etc.

Below the initial issue, you can also see any comments that have been added to the issue:

Comments are very versatile, and provide you a permanent location to have conversations about what is causing the issue, ask for additional information, link to other similar issues, or anything else that is useful. Having these conversations alongside the issue means you have a log you can refer to in future when fixing similar problems.

Note that all comments are written using markdown; you can use @ and a username to tag people in to the conversation, format the text using markdown, and even include emojis 😄

3.5.3 Raising issues

Raising your own issues is very simple! By default, your repos will come with a number of pre-set templates to help you provide the right information in an issue. These templates request slightly different information depending on the type of isse, and ensure that anyone completing them has provided all the information you need to fully consider their request.

To start the process, click on the green “new issue” button in your issues tab! This takes you to a page that allows you to pick whether you’re raising one of two issue types:

  • Bug report: when you’ve spotted a problem with live code that needs to be repaired
  • Feature request (to request the addition of something new to the code).

Select the type of report that is most relevant to the issue you’d like to raise. This then takes you to the template page:

All issues need to be given a title. Provide a title which is clear and summarises in a few words the most important aspects of the issue you’re raising.

Next, complete the body of the issue, following the template prompts provided. Like comments, issues can be completed using markdown to format text and add screenshots and images, however you can also use the formatting menu at the top of the box if you prefer. You can refer to other issues and pull requests on the same repository by using # followed by the issue/PR number, and tag other people using @ followed by their user name.

If you are a repository owner, you can use the assignees section on the right hand side to assign people to the issue. Click on the cog symbol to get a drop-down menu of the people you can assign to the issue. You can do this both before or after issue submission.

You can add labels in a similar way to assignees, by clicking the cog next to the labels section and choosing the relevant tags.

Submit the issue by clicking the green “submit” button at the bottom of the page. This creates the issue, and also sends a notification email to anyone you’ve tagged in the issue, and anyone you’ve assigned to it as well.

You can add assignees and labels after submitting the issue if you like, as well as being able to add comments to the issue to record additional information or ask questions about the progress of the issue.

3.5.4 Tasks

15:00

3.6 Creating branches on Github

Once you’ve identified an issue, you will want to create a new branch. This is where you’ll make changes to the code, rather than risking breaking your live code inside your main branch.

As you already saw in the last chapter, you can create branches within your local repository, and push them up to your remote repository when you’re ready. You can also do this the other way around; create the branch in your remote repository and pull them down into local. The choice of which way to do this is largely personal preference; I prefer to create my branches remotely so they appear to all users at the same time.

You can create branches inside your remote Github repository inside the branch dropdown in the code tab.

Branches are typically created from the dev branch, so first we select the dev branch from the drop downmenu. After doing this, you can type the name of the new branch. If a branch with that name already exists, it will appear in the list below. Otherwise, a button will appear under the branches that says “create branch: branch-name from dev”.

Clicking this button will create the branch as an exact duplicate of dev. Swapping the branch you’re on when creating the branch will change this (e.g. creating a branch when on main will produce a duplicate of main). You can then pull locally to get the new branch to appear in your local repository, and make any changes you’d like there.

3.7 Pull requests

3.7.1 How do pull requests work?

After you’ve made the changes to a branch to fix the identified issue, you can follow the git steps you learned in the last chapter to stage, commit and push those changes up to Github. Eventually, a fix that you’ve created and tested will be available on the new branch you created. At this point, you’ll want to merge those changes from the branch you created into the live code your team is using; to do this, you want to use a pull request.

Pull requests are essentially a way to propose merging changes from one branch to another. Github will automatically check what the differences are between the two branches, note any conflicts, and summarise it all. This gives you the opportunity to do things like link code changes to issues, providing a trail of breadcrumbs for people looking at your repo in future. It also gives everyone working in the repo a chance to review the changes you made, looking for problems and errors and fixing them before overwriting the current live version of the code.

The most common source of git confusion

New users of git and Github frequently get confused between pulling to bring changes from their remote to their local repository and a pull request to merge changes from one branch to another. The two things are not related, and it often helps to think of pull requests as merge requests to avoid this confusion.

3.7.2 Viewing pull requests

Now you’re familiar with Github issues, a lot of the interface for pull requests will feel very similar. Clicking on the “pull request” tab at the top of your repository will take you to the pull request overview page. Here, you can see a summary of all of the pull requests associated with your repository. Hover over the image below to see the different information available on this page:

Your Image 11 Search Open New Issues Details

  • Search your PRs: As for issues, by default when you land on this page, it will show you all open PRs, arranged in chronological order. You can also search to find a particular PR you’re looking for, searching by PR number, key words in the description, or using the Github search syntax to filter.

  • Open and resolved PRs: Move between showing only open PRs (the default) and looking back at closed PRs.

  • Open a new PR: Click this green button to start the process of creating a new pull request (covered in the next section).

  • List of PRs: As for issues, this lists the PRs for your repository, with the name, when it was raised, and who raised it. Clicking on the pull request title takes you into the individual page for that PR, which provides further information.

  • PR details: Details about the PR are shown on the right hand side of the list. This includes labels, assigned reviewers, issues linked to the PR, and number of comments on this pull request.

Clicking on any one of the pull request titles takes you into the overview for this PR:

3.7.3 Creating pull requests

Once again, just like issues, you can click the green box to start the process of creating a pull request. Unlike issues, once you do this the first thing that comes up looks quite daunting!

It’s quite simple when you understand what it’s asking though! To merge the changes from one branch to another, you need to specify both the compare branch (the branch with your changes in) and the base branch (the branch you’re merging the changes into). It can be tricky to get these the right way round, so note the arrow between the two branch names, and imagine your changes travelling in the direction of the arrow (from compare to base).

Make sure the names of the two branches are correct here, and Github will let you know if you can set up a pull request at this point. It won’t let you do so if:

  • There’s already a pull request set up between these two branches
  • The base and compare branches are the same
  • The base and compare branches have no commit history in common (very rare!)

Sometimes you’ll get a message saying you can’t automatically merge, but that’s okay, it won’t prevent you setting up the PR. Click on the green button to continue to complete the PR template:

As for issues, your repos will have a default template for pull requests, which has been designed to ensure that a reviewer has all the information they need to make an informed decision about your PR.

All PRs need to be given a title. A title is often automatically generated, but it’s better to replace this with one which clearly summarises the most important aspects of the PR in a few words.

Next, complete the body of the PR, following the template prompts provided. This is a little more involved than the issue template, and includes:

  • Proposed changes: a plain text description of why the merge has been requested
  • Types of change: check boxes to select what kind of changes have been made
  • Points I have checked in my code: log of what tests the code writer has performed
  • Points for review: any specific points the reviewer should check carefully when doing the review
  • Security considerations: confirmation the writer hasn’t uploaded any secrets in their code
  • Tag a reviewer: use their @ handle to tag them into the review

If you are a repository owner, you can use the referees section on the right hand side to assign people to review your PR. Click on the cog symbol to get a drop-down menu of the people you can assign, you’ll want to make sure at least one person has done a review before merging your changes. You can also use the assignees section in the same way, for people who have been working on the code but won’t be reviewing it.

Submit the PR by clicking the green “submit” button at the bottom of the page.

Once you’ve submitted, you can also use the cog next to the development section to link the PR to an issue (it won’t work before submitting). This keeps track of which PRs have been created to fix which problems, and is one of the most powerful ways to manage your repo. When you have a solution to a problem, you can join the records of the problem and solution together in Github. Looking at one will allow you to see the other; the problem and the solution will always remain linked together, along with comments, reviews, etc. In addition, when you close the PR it also handily closes the issue for you.

3.7.4 Tasks

15:00

  • Create a pull request from the branch you made in session 1 to the dev branch
  • Have a go at changing some of the text and checkboxes in the pull request template, to give an overview of the pull request to your reviewer
  • Tag the person you have been paired with (us the @ and find their username) in your pull request and set them as a reviewer
  • Link it to the issue you created in the previous task (use the # to find your issue)
  • Create the pull request. Have a look around, look at the file changes and commits

3.8 Code reviews

3.8.1 How do code reviews work?

This is it, you’ve finally reached the final step of your workflow! You have already created the pull request that represents the technical process for merging your changes into the live version of the code. However, you can’t merge your changes without a due diligence process; you need someone else to check your code, ensure that it’s written clearly, is robust, and works without breaking any other steps of the process. Github allows you to do a very comprehensive code review, with an interface that lets you add line-by-line comments so it’s easy to link code to comment.

In order to do this, you will want to request a code review from a collaborator. Github offers an easy way to ask for peer review as part of the pull request. Once that review is complete will store any comments and changes alongside the code. This means that just like any other aspect of Github, you can go back in future and see what was reviewed, any issues that were pulled out, and how they were fixed before the code was merged.

Requesting a peer review can be done on any pull request using the “reviewers” option on your pull request, as mentioned in the previous section. Click on the cog symbol to get a drop-down menu of the people you can assign, and click on their names to assign them to code review (they will get a notification you’ve done this).

3.8.2 Viewing and responding to a code review

Once a code review has been carried out, all comments are included in the pull request comment chain, alongside the code it’s related to. You can view any comment chains as part of open or closed PRs, simply by opening the pull request and scrolling down. You can see an example of this below:

When you receive these comments, you can:

  • react to the comment (using the smiley face button below the comment)
  • respond (using the reply box)
  • tag other people in to solve the comment (using @ followed by their user name)
  • quote or link in other comments or issues (using the …)
  • mark comments resolved (with the “resolve comment” button) once they have been addressed
  • create new issues based on points raised in a code review (using the …, followed by “reference in new issue”)

3.8.3 Carrying out a code review

If you’ve been asked to do a code review, a few things will happen as part of that process:

  • The person requesting the review will add you as a reviewer to the relevant PR (as described above)

  • You will receive an email notification that someone has requested your review, letting you know which repo it’s related to

  • When you navigate to the repository, you will see a banner at the top of the relevant pull request, including a “start review” button. You can click this to be taken directly to the reviewing interface.

If you haven’t had a request to review someone’s code, never fear, you can still put your two penn’orth in despite not being asked! You can either:

  • request a review from yourself, and the banner above will appear when you next go to the PR

  • navigate to the “files changed” tab on the PR, which is the same place the button takes you

In the files changed tab, you’ll notice it looks very familiar to the commits overview you saw earlier in this chapter; with the old version of the code on the left, the new version on the right, and changes highlighted in red and green respectively. The only difference is that this view shows an aggregation of all changes made to the files in the pull request, rather than the changes in a single commit.

To start a review, hover over the + or - sign on the left hand side of a changed line (highlighted in either red or green). A blue + button will then pop up.

Clicking on this blue + symbol brings up a familiar interface; you can write a comment in here. Just like every other part of Github, you can use markdown, add pictures, or inline quotes of code to explain what you mean.

When you’ve written your comment, make sure you click the green start a review button, rather than the single comment button. This allows you to add as many in-line comments as you like, as well as giving you the option to write an overall comment.

Work through the file, adding as many in-line comments as you need to. Once you’ve finished, you can scroll to the top of the tab again. Here, there’s a green button that says “review changes”; click this to bring up the final commenting interface.

Here you can add a general comment regarding the overall pull request; are there any overarching issues that need to be addressed, or things that come up repeatedly (or you can just say well done!). You can then select whether to just comment, or specifically approve the changes. Most repositories will be set up to require approval before merging, so make sure you select that option once you’re happy that the changes can be merged.

Once you’ve done this, the owner of the PR will receive a notification, and can go in and merge their PR (in some cases this may happen automatically on approval).

And that’s it! Note that we haven’t gone into much detail on what you should actually be looking for in a code review or how to phrase your comments; we have additional training available on how to do this if you’re interested.

3.8.4 Tasks

15:00

  • Navigate to the pull request you have been tagged in
  • Carry out a review of the pull request
  • Add a single inline comment to it
  • Approve the changes

3.9 Repository structure

3.9.1 The beginning of good practice in Github!!

Most of the content covered in this book so far has focussed on the “how” of Git and Github, and hasn’t covered much in terms of best practice. However, for Git and Github to be useful tools, good practice is absolutely essential. Without it, version control becomes a chore rather than a useful part of your coding practice.

This section touches on the very basics of good repository structure, but good practice in Github goes far beyond that! After these sessions, I’d strongly recommend you work through our Gitflow content as a bare minimum, but also consider attending a Github Technical Lead training session at a future date.

3.9.2 How is a (good) repo structured?

  • One project per repo. Each repo should be for a single coding project. If you can’t simply describe the purpose of a repo, it’s probably time to split it into two!

  • Multiple branches. Every repo will have multiple versions of the same code, stored in different branches. You will always have a live “main” code branch, but you will also have a range of feature, development or bugfix branches.

  • Sensible branch names. Like folders on a shared drive, branches are named after their purpose, not the person working on them. You should be able to understand what changes are being made to the code in that branch.

  • Clear individual commit messages. Each change should be accompanied by a short, clear message which tells you what was changed.