TutorialsManaging branches in Git

To keep work organized, the following Git branching conventions are recommended when working with Pup.

In Pup, we recognize three types of branches:

  • The master branch which contains the latest release currently deployed to the production environment.
  • The development branch which contains the latest release currently deployed to the staging environment.
  • feature|bug|refactor|chore branches which contain work that's actively in development.

To aid in this process, use of the Git Extras library is recommended.

How do I use Git to do my work?

When you're ready to start work on something, you will want to begin by pulling the latest copy of the master branch by typing:

$ git checkout master && git pull origin master

Next, you will want to switch to the development branch and pull the latest copy of that by typing:

$ git checkout development && git pull origin development

At this point, you should have the latest version of the staging environment, also known as the next release to be deployed to the production environment.

Next, you will want to create a feature|bug|refactor|chore branch. Before you start any work, it must have a corresponding issue in the repo on GitHub. If what you need to do does not have an existing issue on GitHub, stop now and go create one.

Once you have your issue created, double-check that you're on the development branch with git checkout development and then, using the Git Extras library you installed above, create your branch with:

git <feature|bug|refactor|chore> <name>_#<issue_number> where <feature|bug|refactor|chore> is the type of branch, <name> is a simplified version of the name you gave the issue on GitHub (e.g., if the name there was "Add ability to send email notification when a new customer subscribes" you might type new-customer-email) and <issue_number> is the number of the issue on GitHub.

For example, a complete command to start a new feature branch may look like git feature new-customer-email_#121. Similarly, a chore branch may look like git chore update-smtp-settings_#53.

Once this is complete, Git Extras will create a new branch in Git on your behalf like feature/new-customer-email_#121 and set up tracking for a remote copy of the branch.

All of your work in relation to this issue should take place in this branch and only this branch! Don't be the drunk in the room knocking the punch bowl off the table.

As you complete work on your branch, you can push that work up to GitHub with git push origin <branch_name>. For example, git push origin feature/new-customer-email_#121.

What do I do when I'm done with work on my branch?

When you've finished your work (this includes both writing the code and any tests to help you confirm its accuracy), you should push your work to GitHub and open a pull request into the development branch for the project.

For example, say we were working a new feature on the branch feature/mailchimp-api_#78. Once all of our work is committed we'd run the following to push our work up to GitHub:

git push origin feature/mailchimp-api_#78

Once this is complete, we'd want to locate the project we're working on on GitHub and navigate to the Pull Requests tab. From that page, locate and click the "New Pull Request" button.

On the following page, ensure that dropdown labeled base is set to "development" and the compare is set to the name of your branch, or here, compare: feature/mailchimp-api_#78. Once selected, click "Create Pull Request" and adjust the title and comment as necessary. It's important to leave as much detail as possible here so we know what we're looking at.

Once this is set, click "Create pull request."

Approval of the pull request depends on your team structure. If there's someone available to review your work (and its addition isn't urgent), assign someone as a reviewer. If you're the only person working on the product, consider asking a friend or do the review yourself.

What if my code fails on Circle CI?

Once your PR is created, you should see a block on the page that explains that checks are being run against it (this will be in yellow). These checks are your tests being run on Circle CI. If your tests fail, you will see a red circle with an X letting you know on your PR on GitHub. If your tests pass, you will see a green circle with a checkmark.

Your code must pass these checks before it will be merged into the development branch and queued up for release.

It's possible that your code could fail when building on Circle CI. Even if you're certain your tests passed on your local machine, from time to time weird anomalies can crop up (e.g., a timeout not working, a code feature like the spread operator being unrecognized, etc.) that can create a false negative.

When this happens, it's important to double-check your code and tests run locally and if all looks well, locate the job in the "Jobs" list on Circle CI, click on its title, and in the top-right hand corner of the page, click the "Rerun Workflow" button to try again.