Pantheon Community

Introduction to GitHub

This is for the developer who hasn’t yet dealt with GitHub. Git can seem like a daunting and difficult tool (and it can be, at first), but contributing to discussion and code in GitHub is actually pretty easy. In fact, you can do a lot without ever having to interact with Git, at least at the beginning.

In this thread, I wanna help those who need it get their feet wet with contributing on GitHub. For full disclosure, this is not entirely without personal motive; Pantheon’s Documentation is hosted on GitHub, so getting you familiar with it gets you closer to contributing to our docs.

Let’s begin by defining some terms:

Repository (or repo)

This encompasses the entire codebase of a project.

Issue

Issues are a way to highlight a bug, request a feature, or generally start a discussion that isn’t directly related to a code change, like a Pull Request is.

Branch

Every repository needs at least one branch. This is usually called master, though the shift is moving progressively to use more innocuous names like main or default instead. Usually, the default branch is what’s built and/or shipped to production/live, and other branches are spun off to work on new features or bug fixes, and then merged into the default branch.

Commit

In Git version control, a commit is a timestamp in the history of the codebase, showing the change in a file or files from something to something else. A common best practice for version control is to group single functional changes (even across multiple files) in single commits, and group larger sets of commits revolving around a common goal into a…

Pull Request

This isn’t a feature built in to Git, but rather one provided by tools like GitHub, GitLab, etc. It’s essentially a proposal to merge one branch to another, providing an easy way to compare the changes submitted, and discuss them in a single location.

Now issues are pretty self explanatory, so let’s talk about pull requests. Did you know you can edit a file and submit a PR without ever touching Git directly? Let me show you:

  1. Browse to the file you want to edit. For an example let’s use, oh I don’t know, Pantheon’s documentation.

  2. Hit the edit button, that friendly little pencil icon, to get an in-browser editor:

  3. GitHub provides an in-browser text editor with line numbers and syntax highlighting. If you’re editing a Markdown or other text format it recognizes, you can use the preview tab to view your changes.

  4. Under the text editor, you can provide a short commit message and an optional longer description. Common practice is to make a commit message as succinct as possible.

    If your GitHub user has the right permissions, you can choose to commit to the default branch (almost never a good idea), or make a branch in the main repo. Otherwise, GitHub will automatically clone the repository for you to make a pull request from:

  5. GitHub will then show you a “diff” of your changes. Click Create pull request to go to the PR template. If the project has a PR template in place, please follow it, as it will help the maintainers review your suggestions.

And that’s really all there is to it! Now you can dip your toes in open-source project contribution without having to learn Git. (You still should learn Git, but we’ll talk about that later).

4 Likes

Thanks for sharing this! Even as someone who does not come from a developer background, I found this really informative & easy to follow along. :clap:

2 Likes