A Guide to GitHub for Non-Developers
By: Jennifer Johnson
Tags: Github, Deployment, Development, Source Control

GitHub

Let’s start with the big guns: GitHub. GitHub is where we keep all of our code, it’s DropBox for developers. Code is split into repositories (or repos) which are akin to project folders on your computer. Most of the time a distinct app or service has its own repo. E.g. the next-article repo for the article page app.

Things a developer might say:

Something’s broken but I haven’t figured out which repo it’s in 🧐

If you look at a repo in GitHub the code you will see is called the main branch. A branch is a bit like a sub-folder, and the main branch contains the code that exists in production, i.e. if you look at the main branch on the next-article repo you will see the (nicely formatted version of the) code that gets run when you load an article page on FT.com.

Working locally

A repo will usually have other branches too; these are copies of the main branch which have been edited in some way, usually because a developer is in the process of adding, fixing, or otherwise changing something.

When a developer wants to make any changes to the production code they do so on their own laptop on a copy of the repo they have cloned there. This is called working locally. They do this work on a branch so that their changes aren’t reflected in the production code until they’re happy with them.

Multiple times a day a developer will commit and push the changes they’ve made locally to GitHub. This saves the changes to GitHub and these are the branches you’d see if you looked at a GitHub repo.

Which branch is that on? 🤔

Whyyyyy can’t I get this running locally?!!! 😩

Let me just commit these changes before I go 🍺

Merging

When a developer is happy with their code they will create a pull request (PR) asking for it to be reviewed. In a pull request a developer explains the changes they’ve made in the code. Other team members review the changes and approve the PR or leave comments asking for changes.

Creating and reviewing pull requests is the part of this process where there’s a dependency on other people and can be time consuming, although it’s very worthwhile. Good pull requests make it as easy as possible for people looking at the code in the future to understand what decisions were made to get it to that point.

Once the PR has been approved it can be merged into the main branch.

My PR is almost ready to go 🙌 (i.e. almost ready to be reviewed)

Pleeeeeeeeeease can someone review my PR? 🙏

Deploying

Once a PR has been merged the code from the developer’s branch will be contained in the main branch, but it won’t yet show up on the website. For that to happen it needs to be deployed.

Deploying means getting the code from where it’s stored, in GitHub, onto the servers that host the site, in our case on a platform called Heroku.

Because of some wondrous thinking by the FT developers of yore about how to make deployment as easy as possible, the deployment process starts automatically when a PR is merged in GitHub. We use another tool called CircleCI to manage our deployments.

CircleCI takes the code from GitHub and builds and deploys it.

In building the app, CircleCI takes the code that’s in the repo and does a load of stuff to it that makes it ready to run in production. (Like all development, this process is like fractals — you can get more and more in depth about what it entails until you’re just dealing with the zeros and ones, but for the purposes of this blog ‘stuff’ will do).

CircleCI then runs a final set of tests on the code and deploys it by saving it to the relevant app server on Heroku. Once the code has successfully been deployed it will be visible in production within minutes.