t0ul

Automate the Boring Stuff with Go, Ch. 0.4: GitHub

· 6 min read · #golang, #automate-the-boring-stuff-with-go

Part of Automate the Boring Stuff with Go, a beginner-friendly guide to programming in Go.

git keeps history on your machine. GitHub is a website that keeps a copy of that history where other people can see it, and where strangers send each other changes. Nearly every Go package this book imports lives there, the book’s own code lives there, and by the end of this chapter you will have made a change to it that the author merges.

An account

Sign up at github.com with the email you gave git in 0.3, so your commits and your account match. Pick the username carefully; it ends up in the address of everything you publish, github.com/yourname/project, and changing it later breaks links.

Turn on two-factor authentication straight away: Settings, Password and authentication. GitHub requires it for anyone who contributes code, and a passkey or an authenticator app is the easiest form. Two-factor is what stands between a leaked password and someone pushing code as you, and on GitHub “as you” means into every project that trusts you.

Reading a repository page

Open the book’s repository: github.com/t0ul/automate-the-boring-stuff-with-go. Every project on GitHub has this same page, so once you can read this one you can read all of them.

  • The file list is the folder you cloned in 0.3’s sense: ch1, ch2, go.mod, README.md. Click into folders and files the way you would in a file manager; GitHub shows code with colours and line numbers.
  • The README is rendered below the file list. It is the front door: what the project is, how to run it. This one tells you how to run any chapter’s program.
  • Commits (the clock icon with a number, above the file list) is git log for the whole project, with every change readable.
  • Issues is where people report problems and ask questions. Pull requests is where they send changes. Both are public, searchable, and usually the fastest way to find out whether your problem is known.
  • Releases, on the right, is where projects publish built downloads. Chapter 16 makes one.

Getting the code onto your machine

Two ways, and both are fine.

Clone makes a full copy with the whole history, and it can be updated later:

cd ~
git clone https://github.com/t0ul/automate-the-boring-stuff-with-go.git
cd automate-the-boring-stuff-with-go
ls

LICENSE
README.md
ch1
ch10
...

The address came from the green Code button on the repository page. When the book changes, come back to this folder and type git pull; git fetches the new commits and updates your files. Everything in Part I onwards assumes you are standing in this folder.

Download ZIP, from the same green button, is a snapshot with no history and no way to update. Perfectly good for reading along; you can always clone later.

Either way, this is someone else’s repository. You can run it, edit it, break it, and nothing you do reaches GitHub, because you do not have permission to write to it. For that there is the pull request.

Opening a good issue

When a program in the book does not work on your machine, open an issue: the Issues tab, New issue. A good one has three parts, and they take two minutes:

  1. What you did. The exact command, copied from the terminal, and which chapter.
  2. What happened. The error, copied exactly, not retyped. Use the up arrow and select the text.
  3. Your setup. Operating system and the output of go version.

Paste terminal output between triple backticks, ```, so it keeps its shape. That is also how code and output are formatted in every comment and pull request on GitHub, and in this book.

Search Issues before opening one. Someone with the same error may be a click away from the fix.

Your first pull request

A pull request is a proposal: “here is a change to your project; please take it”. It is how all open-source software is built, and it is how you will send fixes to the libraries you use once you are good enough to spot them. The book’s repository has a file whose entire purpose is to receive your first one.

Open CONTRIBUTORS.md in the repository. It asks you to add your name on a line of its own. Here is the whole flow, in the browser, with no git commands at all:

  1. With the file open, click the pencil icon above the file content, labelled Edit file. GitHub tells you that you cannot edit this repository directly and offers to Fork this repository. Click it. A fork is your own copy of the project under your account, where you do have permission.
  2. Add a line at the end of the list in the form - Your Name (@yourhandle).
  3. Click Preview to see how it will look, then Commit changes… at the top right.
  4. In the dialog, write a commit message, as in 0.3: Add my name to the contributors. Click Propose changes. GitHub commits to a branch in your fork and shows you a comparison between your copy and the original.
  5. Give the pull request a title and, if you like, a sentence in the description. The repository shows a short template with two questions; answer them or delete them. Click Create pull request.

That is it. The author gets a notification, reads the change, and merges it. Your name appears in the file in the original repository, and the pull request page keeps a record of the conversation forever. Pull requests to real projects go exactly the same way, with the difference that someone may ask you to change something first; that conversation happens on the pull request page, and you push more commits to the same branch until everyone is happy.

Two words you met for the first time just now. A fork is your copy of someone else’s repository on GitHub. A branch is a separate line of history inside a repository; GitHub made one for your change (it names them patch-1, patch-2 and so on) so that your proposal sits beside the project’s main rather than on top of it. Chapter 0.3 kept to one branch on purpose. When you start making larger changes, a branch per change is the habit, and you now know what the word means.

Publishing your own project

You will want this by chapter 16. On GitHub: the + menu at the top right, New repository, a name, leave it empty (no README), Create repository. GitHub shows the two commands for connecting an existing local repository; for the practice repository from 0.3 they are:

git remote add origin https://github.com/yourname/notes.git
git push -u origin main

origin is the conventional name for “the copy on GitHub”. After the first push, git push alone sends new commits up, and git pull brings down anything that changed there. The first push asks you to sign in; GitHub walks you through it in the browser.

Conclusion

You have an account with two-factor turned on, the book’s code on your machine with a way to update it, the vocabulary to read any repository page, a template for a useful bug report, and a merged pull request with your name on it. That is more GitHub than many working programmers used in their first year.

Part 0 is done. Chapter 1 installs Go and an editor, and the terminal you open there will feel like a room you know. And when you want git and GitHub properly, with the habits that keep a repository safe, there is a short book for exactly that: Git and GitHub the Safe Way.

← Back to the blog