Branches and Pull Requests

Aims and Objectives

Branches allow you to develop features, fix bugs, or safely experiment with new ideas in a contained area of your repository. They can be particularly useful when collaborating within a team, allowing for independent development of different areas of the repository that do not interfere with each other. This skills session will use directed, interactive lessons to provide NOAA Fisheries staff with a foundation in using branches in concert with pull requests for collaborative development.

Prerequisites: What do I need before this workshop to follow along on my own?

  1. This stand-alone skills session is meant for those with a basic understanding of Git and GitHub. Check out our Introduction to Git and GitHub lessons if you are new to Git and GitHub or need a refresher.
  2. We will also be using a bit of Markdown, so you may want to refresh yourself on Markdown language with our Introduction to Markdown lesson.

What is a Branch?

Tutorial: Making and merging a branch

For this tutorial, we’re going to be forking a demo repository (https://github.com/nmfs-opensci/GitHub-Clinic-demos), making a branch on our forked copies, editing our forked copies, and creating a pull request to contribute back to the main branch. Follow along on your own account.

Step 1: Fork the repository

  1. Open the demo repository in GitHub.
  2. At the top of the repository, click the Fork button
  3. Keep everything default (your account should be listed under Owner, and the Repository name should be pre-filled for you). Click the green Create Fork button.

Step 2: Create a new branch

  1. On the Code tab of your forked repository, click the dropdown menu where it says main
  2. In the text box where it says “Find or create a branch”, type the name of your branch. Let’s call it tutorial. Click the Create branch tutorial from main button to create your branch.

Step 2: Add content to your new branch

  1. Let’s add a new file to our repository. Click the Add file (+) drop-down menu, and click Create new file.
  2. Name your file intro.md and add some content to your file. If you’d like, you can copy the following markdown chunk and paste it into your file.
# Introduction

This repository serves as a sandbox demo for the NOAA Fisheries GitHub Clinic. Feel free to fork this repository and use it to practice Git and GitHub tools and methods.
  1. Commit your changes to the tutorial branch.

Step 3: Create a pull request

  1. Click the Pull requests tab at the top of the repository. GitHub should recognize that you made a push to your tutorial branch. Click the green Compare & pull request button to start a pull request to merge the pushes from tutorial into main.
  2. Notice that because we’re working from a forked repository, GitHub will automatically fill in the parent repository (nmfs-opensci/GitHub-Clinic-demos) as the repository to merge into. For this tutorial, we instead will merge into the main branch of our forked copy of the repository. Click the drop-down menu where it says “base repository:” and select your forked copy.
  3. GitHub will pre-populate the title of our pull request based on the commit message. If we have multiple commits, we would need to make our own pull request title. Make sure the title is clear and concise, and add a detailed blurb to the description section. For our example, this can be as simple as describing the intent of the pull request. For more complex pull requests that involve adding to or modifying code and text in multiple files, we want to guide the reviewer through your changes as much as possible. Be as detailed as you need to be to convey the changes that were made and why they were made. You can even add images, screenshots, videos, and links to showcase how the changes you made are reflected for the end user.
  4. Click the green Create pull request button to finalize our pull request.

Step 4: Review and merge your pull request

Reviewing a pull request is an important step of the collaborative process on GitHub. Pull request reviews allow the owner of a repository or another collaborator to read through changes line-by-line, adding comments and proposing edits along the way. Think of a pull request review as being similar to a manuscript or report review using track changes.

Before we merge our changes into our main branch, let’s get some practice with reviewing pull requests. This step is not as important when you’re the only one working on a repository (like in our tutorial), but it’s good practice for future collaborations.

  1. Assign yourself as a reviewer to the pull request using the Assignees dropdown on the right-hand side of your pull request. In a collaborative setting, you can assign up to 10 of your collaborators.
  2. Navigate to the Files changed pane in the pull request. This is where we’ll conduct our review.
  3. Just like in a manuscript peer review, we can leave a narrative review with general comments and recommendations, and we can also add comments and propose edits to specific lines. Let’s add a comment to change the first-level heading of our markdown file. Hover your mouse in the space between the line numbers and the content. You’ll see a highlighted + icon appear next to each line. Click the + icon next to line 1.
  4. This will open up a dialog box where we can add a comment or suggest a change to this specific line. Lets suggest a change to the heading name. Click the icon next to the Preview tab. This icon is the Add a suggestion icon. Notice that when you click this icon, it inserts a code snippet into our dialog box with the label suggestion. Inside this code snippet, suggest a change to the # Introduction header to read # Purpose of this repository.
  5. From here, we can either add our suggestion as a single comment to the pull request conversation, or start a review based on this suggestion. Let’s go ahead and click the green Start a review button.
  6. From here, we can add more line-by-line comments and suggestions, or we can finish our review with our general impressions. Let’s click the green Finish your review button (notice there is a ticker that tracks the number of line-by-line comments/suggestions).
  7. Add a comment to your review summarizing your comments and changes and giving overall impressions. Click the green Submit review button to finalize your review.
  8. As the original creator of the pull request, you can now commit the proposed change directly to the pull request, continue the conversation to refine the suggestion, or decline the suggestion and Resolve the conversation. Let’s commit the proposed change from the pull request review.
  9. Once your change has been committed, we’re ready to merge the pull request! Click the green Merge pull request button, and confirm your merge with a merge commit.

  10. Congratulations! You have merged a pull request from a branch. You can now optionally delete the branch (don’t worry, you can always restore it from the pull request). During the next GitHub Clinic session on Git Workflows, we’ll discuss reasons and scenarios where you may want to keep a permanent branch versus creating and deleting ephemeral branches for development. For now, let’s go ahead and delete our branch to close out this tutorial.