Understanding GitHub Concepts
Working with GitHub is easy once you understand a few basic concepts.
To start, it's important to understand the repository (or repo) structure of GitHub and how you can work with it. To make changes to the design documentation, you must manage three copies of the repo:
- An Upstream copy where approved documentation that displays on the website lives.
- An Origin copy which lives in your personal GitHub account and is created by forking the upstream repo.
- A Local copy which lives on your desktop machine and is created by cloning any remote repository.
This diagram illustrates these three repos and how they are related.
During the editing process, changes are first introduced to your local repository using a text editing application. To make sure that you are working with the most recent files before making your edits, you always should start by pulling updates from the upstream. Doing a pull will synchronize your local repo with the upstream master.
When you are ready to submit changes to GitHub you will make a commit and push them to your origin repo. A Commit can bundle multiple changes into package that can be submitted to GitHub as a whole. Following your commit with a Push will upload changes to your personal GitHub account.
At this point your edits are only visible to you and you must create a pull request to submit them to the upstream. As its name suggests, a pull request is a request to the upstream repo to pull your changes and update the associated upstream files. A pull request sits in a queue and does not actually apply any changes to the upstream master until it has been reviewed and merged by a repo maintainer. By not allowing contributors to push directly to the upstream master, GitHub preserves the integrity of the code base while allowing multiple contributors to submit changes at will.
It's not uncommon to be working on multiple feature updates at one time. That's where branching comes in. By creating a feature branch of your local repo you are allowing separate changes to be isolated from each other. We recommend that you always create a new branch when starting work on a feature or issue that you plan to address. This will allow you to submit one set of changes while continuing to work on another without combining these all into a single request.
For your reference some common terminology can be found below. Now that you have been introduced to some high level concepts, let's take a look at how to set up your contribution environment.
This is a list of common, Git-specific terms and how they apply to the PatternFly contribution process. Other organizations may not use these terms in exactly the same way.
Branch: A different version of a repository that contains a simultaneous but separate set of changes. Multiple branches are required in order to have multiple open pull requests.
Clone: Copies a remote repository to your computer.
Fork: Creates a personal version of a public repository.
GitHub: A website that hosts Git repositories and where a large number of open source projects are housed.
Local: A local copy of your origin repository. Commit and push your changes regularly to make sure that they are backed up.
Main: The main branch of a repository. Generally, changes should not be made on this branch unless you are absolutely sure that you will not want to submit a second pull request until your first one is merged.
Merge: Combines together two different versions of a repository, incorporating both of their changes into the end result.
Origin: Your version of a repository. Changes are restricted to your account until they are merged into the upstream repository. (Stored on GitHub)
Pull Request (PR): A request to incorporate your changes into a repository to which you do not have write permissions. Only a single pull request can be open from a single branch at a time.
Repository: A special Git-enabled folder that can save and restore different versions of itself.
Upstream: The main project repository. All contributed work is stored here. (Stored on GitHub)