Using GitHub

Summary

We share a lot of our work open source on GitHub: This handbook, our code, and much more. Open source also means anybody can propose changes - it is a critical tool for how we invite you to co-create.

Why GitHub?

GitHub is a place for people to gather, create, and share their work publicly.

For us, sharing our work on GitHub is about ensuring that we are open about how we create things. Working open is not only about sharing the end results, but about actively inviting people into the process. GitHub is an essential tool to do this, and anything we write is open source.

GitHub was originally intended for code, but don’t let that scare you - we are here to help you along the way and get you the skills you need. We are using it for writing like this handbook too!

Getting started

Here’s what you will need to be able to do:

  • Understand general terminology
  • Start discussions
  • Participate and check-in on discussions
  • Participate in reviews
  • Suggest edits to existing documents

We will walk you through everything, step by step. If you already know this, feel free to skip to the Exercises 😊

Terminology

Repositories

On your computer, you may have folders for different projects. On GitHub, instead of folders, you have “repositories.” Each repository contains that project’s files. For example, the repository for this handbook contains this entire website.

Each repository contains a history of all the changes. This is helpful because it allows us to always go back to older versions if things go horribly wrong.

You can watch, fork, and star a repository. Watching a repository is subscribing to its updates (you will receive notifications of ongoing discussions). Forking a repository means creating your own copy of it. Starring a repository saves it as a favorite (an important metric for popularity too).

Issues

Issues are the primary place for open questions. Each repository has a so-called “issue tracker.” This is a great place to make suggestions and participate in discussions on how to change things.

Anybody on GitHub can start an issue, so opening an issue does not mean it will be resolved. When opening an issue, it is important to communicate effectively and focus on making sure you provide all the relevant information to understand what needs to be resolved (communicate for the person reading it).

Pull Requests

A repository goes through many changes - a pull request (PR) is a proposed change that is requested to be incorporated into the main version. It is good practice to only make changes using pull requests when a project hits the first complete version.

We maintain a “minimal pull request” standard. This makes it easier to manage many changes over time, as the energy needed to understand one pull request remains minimal. For example, if you’re substantially editing this page in the handbook, you might realize you also found a typo in another page. A minimal pull request would mean you separate the edits for this page and the typo on the other page into two pull requests. It may also mean you split the edits on this page into multiple pull requests if they are unrelated (e.g., correcting typo’s and adding a whole new section).

Starting discussions

Participate and check-in on discussions

Participate in reviews

Suggest edits to existing documents

That is pretty much it. Creating new repositories are for specific roles only, so if your role requires it, you will receive additional training. Overall, there is a lot more to GitHub, and this is to get you started. Don’t try to learn everything at once (it’s a lot!). More often than not, you only need to know a few things - not all the technical details. 😊

Exercises

Getting help

If you need assistance at any time, ask in the #help channel on Discord. You don’t have to learn on your own, and when you ask questions you can learn from all the expertise available in the community đŸ€©

Saying hello 👋

  • Chris Hartgerink - @chartgerink - I enjoy writing on my personal blog
  • Maya Anderson-Gonzalez - [@mayaandersongonzalez(https://github.com/mayaandersongonzalez] - I also enjoy (and wish I had more time for) writing on my personal blog
Want to learn more about git?

GitHub uses the software git under the hood. Knowing more about this software enables you to realize the potential of this power tool. Here’s a great game to help you get started: https://ohmygit.org/