Skip to content

GitHub flow (branching)

Jump to bottom
Jesse Mathews edited this page Feb 8, 2019 · 9 revisions

People use different workflows to contribute to software projects, but the simplest and most effective way to contribute on GitHub is the GitHub flow.

📺 Video: Understanding the GitHub flow

Branches are an important part of the GitHub flow because they allow us to separate our work from the master branch. In other words, everyone's work is safe while you contribute.

📺 Video: Branches

Tips for using branches

A single project can have hundreds of branches, each suggesting a new change to the master branch.

The best way to keep branches organized with a team is to keep them concise and short-lived. In other words, a single branch should represent a single new feature or bug fix. This reduces confusion among contributors when branches are only active for a few days before they’re merged 📖 into the master branch.

Creating a branch allows you to make modifications to your project without changing the deployed master branch. Once you have a branch, it’s time to create a file and make your commit!

Commits 101

When you’re finished creating or making changes to a file on GitHub, scroll to the bottom of the page. Then find the "Commit new file" section.

In the first field, type a commit message. The commit message should briefly tell contributors about the changes you are introducing to the file.

Rules to live by for commit messages:

  • Don’t end your commit message with a period.
  • Keep your commit messages to 50 characters or less. Add extra detail in the extended description window if necessary. This is located just below the subject line.
  • Use active voice. For example, "add" instead of "added" and "merge" instead of "merged".
  • Think of your commit as expressing intent to introduce a change.

Now that you’ve created a commit, it’s time to share your proposed change through a pull request! Where issues encourage discussion with other contributors and collaborators on a project, pull requests help you share your changes, receive feedback on them, and iterate on them until they’re perfect!

Pull requests

Let’s think back to the GitHub flow again. You have created a branch, added a file, and committed the file to your branch. Now it’s time to collaborate on your file with others. This collaboration happens in a pull request. Check out this video to learn more:

📺 Video: Introduction to pull requests

Pull Requests Reviews 101

Reviewing a pull request is an opportunity to examine another contributor's changes. While reviewing a pull request, you can extrapolate how someone else solved a problem. It's an awesome opportunity to learn more about how the code works and how others solve problems. Reviewing a pull request is a great learning opportunity!

Add assignees for issues and pull requests

Assignees on issues and pull requests let other team members know who is responsible. The assignee oversees the issue or pull request in an accessible and visible way.

⌨️ Activity: Assign yourself to this issue

  1. On the right side of the screen, click the assign yourself text under the Assignees section

Commenting on Pull Requests

As a collaborator on a repository, you will get and give pull request reviews before merging code. This is important! It ensures quality code and maintains momentum of changes to your project.

Responsibilities of a reviewer

As a pull request reviewer, your role is to help the pull request author (thats me!) by making sure:

  • Code destined for production is of the highest quality
  • Intentional shortcuts (technical debt) are commented on and confirmed
  • The greater team is aware of potential risks associated with changes

These broad responsibilities can include more specific goals, like:

  • Pointing out potential issues in code quality, security, or business logic
  • Suggesting other reviewers to the author, when warranted
  • Commenting on, approving, or requesting changes on the PR
  • Providing suggestions for alternate or better implementation details

Some repositories use a CODEOWNERS file. The CODEOWNERS file assigns responsibility for certain parts of the code to specific individuals or teams. When the CODEOWNERS feature is enabled, only the code owner has the final authority to approve the pull request. Your review may not be a formal approval, but it does show confidence.

Communicate in pull requests

When an approval or request for changes is not yet needed, consider using comments. Comments enable you to inquire about the proposed change early in the review process. You don't need to wait until something is complete to make suggestions.

⌨️ Activity: Comment on my pull request

  1. On the pull request, click Files changed
  2. Hover over the line of code where you'd like to add a comment, and click the blue comment icon
  3. In the comment window, type a question or leave a more general comment
  4. When you're done, click Add single comment

Clone this wiki locally