How to Use GitHub Branches

Getting Started with GitHub

--> https://guides.github.com/introduction/flow/ <--

While working on this project using GitHub, we will manage the workflow and commits through branches. Branches will consist of several code commits, and they can include tags, discussions, and other types of review before separate branches are merged back into the primary branch of the project, called master. When you create a branch, you can then open a pull request which is the preliminary stage before merging a branch back into master.

By using branches instead of direct commits to master, we better condense commits made to the project into more well-themed areas, as branch merges can be given names, such as "Portrait Additions" implying the branch contains several commits affecting portrait graphics, or "Dalaran Government Redux" implying the commits in this branch/pull request affect an overhaul of Dalaran and its gameplay attributes, etc. By doing our commits in this way, we can better compile patch/expansion notes, hunt down pesky bugs, and create developer documents.

Now let's get into how to use all of these fancy new tools; it may seem like a lot, but it's easy to get used to the flow.

Branching is a core concept of Git repositories, and GitHub is utterly dependent on them for flow. However, there's one rule: anything that is in the master branch is always deployable. So, we must create separate branches and test them before implementing them into master or we may end up with an undeployable and broken master.

How to Start Using Branches/Pull Requests:

Creation of Branches

1. Begin by viewing the Code tab of the repository. In this case, it will be the Warcraft-Guardians-of-Azeroth repository. (Warcraft-GoA-Development-Team/Warcraft-Guardians-of-Azeroth)
2. Click on the Branch button just above the interface displaying repository files.
3. Type in a new name for your new branch. Try to be descriptive (e.g. add-troll-unit-models or flag-update-centaurs) so that other Tinkers can see what the branch work entails.
4. Now that the branch is created, it is now a separate environment from master, allowing you or other Tinkers to make changes that won't affect master up until the final merge. You can now edit the files to your heart's content, outside of the master branch and inside of your new branch, instead.

Commiting

1. Whenever you make any changes (i.e. add, edit or delete a file), you are making a commit and adding them to your branch.
2. By committing, we create a transparent work history so that we may follow to understand what's been done and why, and they are all considered a separate unit of change. This also allows us to roll back changes if bugs are found or decided to head in a different direction. By writing clear commit messages, it becomes easier for others to follow along and/or provide feedback/debug.

Pull Requests

Pull requests allow for the discussion and testing of work done before it is merged with the master branch. There's different ways to create pull requests, the intermediary step before merging your branch with master.

First Way

1. The first way involves selecting the Pull requests tab of the repository up top, and then clicking New pull request.
2. You will be brought to the Comparing changes interface, which lets you see current branches and all of their current commits/changes. For our purposes right now though, you can simply select one of your new branches under compare: and create a new pull request.

Second Way

1. When editing, uploading, or deleting files from your branch, GitHub will give you two options, normally, at the bottom of your screen: Commit directly to branch, and Create a new branch & pull request.

When creating a pull request, you have the option to select different teams you may want to review your changes, choose assignees if combining work with someone else, label your changes (Do This), and select what projects/milestones your changes contribute to.

Important: When you create a pull request and it is not ready to merge with master, please insert (WIP) into the title of the pull request. This will have GitHub mark it as unready for merge.

Now What?

Now, you have a environment in which you can commit without modifying master just yet, and a transparent work history of all of your commits of that particular branch. Others can give feedback or even test your work from a pull request/branch! Comments on pull requests allow emojis, pre-formatted text, and embedded images.

Deploying Your Branch

With GitHub, you can deploy from a branch for final testing before merging to master. Once the branch passes whatever review you deem necessary, you can deploy the changes and verify them in production. If issues are caused, you can roll them back by deploying the pre-existing master into production.

Merging Your Branch

Once your code is verified and reviewed, you're ready to merge into master. Once merged, pull requests preserve a record of all historical changes to the code.