Make Customizations Available to Your Project Team

Learning Objectives

• Describe what a Pull Request is and when to use it.
• Describe how a feature branch on GitHub works.
• Explain how to collaborate with others on Git projects.

It’s time for Tasha to get these customizations into a feature branch for Isabel to review the work. Using feature branches helps ensure all customizations are reviewed and approved, and keeps different sets of changes isolated from one another.

Create a Feature Branch on GitHub

Branches are used to isolate your development work, or “features,” from other team members’ changes. Create a feature branch and add your changes to it:

1. Open your repository in GitHub Desktop. You should see your changes from the last module, which you pulled from the dev scratch org.
2. Select the tab named Current Branch: main.
3. Click New Branch, to create a new branch off of main.
4. Enter feature/deliveries for the branch name and click Create Branch.
5. Select Bring my changes to feature/deliveries. This tells GitHub Desktop that you want the changes you’ve already made to start out your new branch.
6. Click Switch Branch.

Now on the feature branch, it’s time to create a commit to preserve these changes. A commit is a defined point in the history of your project: with a commit, you add the changes you’ve made to version control.

1. Enter a Summary and Description indicating what you've changed: Created Delivery and Delivery Item objects.
2. Click Commit to feature/deliveries.

Push Changes to GitHub

Currently your new branch with your customizations are stored on your computer. Share this with team members by pushing the changes to GitHub, where you can request for another person to review your proposed changes by creating a Pull Request. Pull requests provide a way for teams to track, review, and combine team members' work. 

1. Publish your changes in GitHub. In GitHub Desktop, make sure you have your feature/deliveries branch selected, and click Publish Branch.
2. Create a pull request; select Branch > Create Pull Request. GitHub opens in a browser window.
3. The pull request’s body is populated with several headers. CumulusCI handles generating cumulative release notes for your project's releases using content entered in the body of pull requests. Edit the following sections:
   1. In Changes, enter a description of what you did, such as, - Created Delivery and Delivery Items objects and fields.
   2. In Issues Closed, enter - Fixes #1, since 1 is the issue number you created in Unit 2 of this module: Make and Capture Development Changes.
4. When you’re finished adding details about the changes you want to make, click Create pull request.

Later in this unit, you’ll learn how to merge this pull request into your main branch. 

Collaborating on Pull Requests

Pull requests and branches help support collaboration. You use pull requests when you need your colleagues to review your changes and run your customizations through a Quality Assurance (QA) process. 

Let’s take a look at how Tasha and Isabel work through the review and approval process on Tasha’s customizations. This is the first time Isabel’s collaborating on the project, so the first step is for Tasha to add Isabel as a collaborator with Write permission on the GitHub food bank repository. She does this within the GitHub Settings tab in the browser. Now that Isabel has access to the repository, Tasha adds Isabel as a reviewer on her pull request.

Isabel is all ready to start reviewing Tasha’s work! Her first step is to look at the pull request in the GitHub repository in the browser. When she looks at the Files changed tab, she's able to explore the changes to the application’s metadata line-by-line, and add review comments to help Tasha clarify her work and identify possible risks. To see the full scope of the changes, Isabel might also spin up a scratch org based on Tasha's branch. If Isabel doesn't already have a copy of the Food Bank repository on her computer, she'll need to clone the repository before building a scratch org on her computer.

Having reviewed the code and seen Tasha's customizations in action, Isabel is ready to approve Tasha's work. She does this in GitHub, by clicking Review changes and selecting Approve, and Submit review. She can then merge Tasha’s work into the main branch of the repository so it becomes part of the package.

Because you’re doing this on your own, you’re going to skip many of the early steps of reviewing, but let’s take a look at how you'd review the customizations in a different scratch org and then merge the pull request into the main branch.

Review the Changes in a New Scratch Org

1. In GitHub Desktop, select Repository→Open in Visual Studio Code to open the current repository and branch.
2. Build a scratch org based on the feature branch; in the VS Code Terminal, type this command: cci flow run qa_org --org qa
3. When the scratch org is ready, open it in your web browser with this command: cci org browser qa

Take a look around the scratch org to confirm the customizations you made, including:

• Two new custom objects, Delivery and Delivery Items
• Deliveries has a custom tab available
• Delivery Items is a related list on the Deliveries object
• The custom fields are the correct field types

Merge the Changes into the Main Branch

Now that your pull request has been reviewed, you can merge the changes into the main branch. When you’re working on a team, like Tasha and Isabel, typically the person reviewing the work will merge the changes into main.

1. In your web browser, on the Conversation tab of the pull request, click Merge pull request to merge your feature/deliveries branch into the main branch.
2. Click Confirm merge.
3. Click Delete branch to delete the feature branch. Like scratch orgs, feature branches are designed to be temporary and are no longer needed once the customizations in them have been merged into the main branch.

The very last step is to clean up the workspace before you leave. 

1. Return to GitHub Desktop.
2. Verify that Current Branch is feature/deliveries.
3. In the GitHub Desktop menubar, select Branch→Delete and confirm that you want to delete the branch feature/deliveries.
4. GitHub Desktop automatically takes you back to the main branch as your Current Branch.
5. Select Repository→Pull from the menu to bring down the changes you merged from feature/deliveries on GitHub. Your registry will refresh.
6. Lastly, in the GitHub menubar, choose Repository→Open in Visual Studio Codeto open VS Code’s Terminal window, and delete your scratch orgs.
   1. To remove your dev scratch org, type this command: cci org scratch_delete dev
   2. If you also created a scratch org to review a Pull Request, remove the second scratch org. Type: cci org scratch_delete qa

With the new customizations in the main branch of their Food Bank repository, Tasha and Isabel will see the changes in every scratch org they create.

Resources

• Trailhead: Git and GitHub Basics
• Get Help: CumulusCI group on the Trailblazer Community