-
Notifications
You must be signed in to change notification settings - Fork 1
GitHub flow (branching)
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.
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!
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.
- 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!
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
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!
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.
- On the right side of the screen, click the
assign yourselftext under the Assignees section
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.
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.
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.
- On the pull request, click Files changed
- Hover over the line of code where you'd like to add a comment, and click the blue comment icon
- In the comment window, type a question or leave a more general comment
- When you're done, click Add single comment
You can also approve or request changes on my pull request.
When you get asked to review something, you should acknowledge the request. Acknowledging a review request could take several forms. It could be leaving a comment on the pull request or leaving a review. In some cases, it could be rejecting the review request altogether.
Before you review, some things to consider
Review the title and body of the pull request to understand the intended change. This should help you identify limitations, boundaries, and other important context.
As a reviewer, there are certain things to look for when identifying how to best provide feedback. In early stages, reviews should focus on the general direction of the changes. Identify if the goal is possible, rather than nitpicking the style, polish, or wording. Pull requests that are closer to merging should receive a robust review. Thorough testing is one of many ways to ensure the changes won't break the project.
Regardless of timing, focus your feedback on the most essential changes. Suggest changes for minor issues within the pull request. When suggesting major changes, open a separate pull request against the author's branch.
- In the pull request, click the Files changed tab
- Review the changes in the pull request by commenting on specific lines
- Above the changed code, click Review changes
- Type a comment summarizing your feedback on the proposed changes
- Select Approve to approve merging the changes proposed in the pull request
- Click Submit review
Sometimes, the author might identify that something isn't working. They might need a helping hand 👋 to solve the problem. In other instances, it might only work in their environment. When reviewing a pull request, look at and test the code to pinpoint any bugs or unexpected behavior.
Reviewing the diff, the comparison of the proposed code, in the context of the whole project. Could it introduce performance problems, or security vulnerabilities? Try to predict unintended consequences that this change could cause.
For most things, actually trying out the proposed change is a good idea. This makes it a lot easier to tell if the actual change matches the intention. You can do this by:
- Cloning the repository, and checking out to the branch compared in the pull request. Run the application in your local development environment.
- Deploying the pull request to a review-lab or staging environment (as appropriate).
When summarizing your review, let the author know if you completed any of these tests.
The goal of providing feedback on a pull request is to ensure that the best possible change is being added. Sometimes, a change isn't addressing the problem in the best possible way. It's the reviewer's responsibility to provide meaningful and constructive feedback.
Before you submit your review, your line comments are pending and only visible to you. You can edit pending comments anytime before you submit your review. To cancel a pending review and its pending comments, scroll down to the end of the page in the Conversation tab. Then click Cancel review.
If you could check out this code for me and tell me what is wrong, that would be fantastic.
- On the pull request, click Files changed
- Hover over the line of code where you'd like to add a comment, and click the blue comment icon
- In the comment window, type your comment
- Click Start a review
- If you have already started a review, you can click Add review comment
- Above the changed code, click Review changes
- Type a comment summarizing your feedback on the proposed changes
- Select Request changes to submit feedback introducing changes necessary before merging
- Click Submit review