Pull request process for devs and individual contributors

This document outlines the pull request process for the PHPeons team and the environments they work on. Please check with your team for guidelines on their pull request process, as it may differ from this document’s guidelines.

PHPeons environments this process applies to (as of 6/23/22):

• relias.com

• relias.de

• mediakit.nurse.com

• distancecme.com

• blog.wcei.net

Overview

A pull request, also known as a merge request, is an event that occurs when a developer or contributor is ready to have their code reviewed and merged into a project or environment’s main repository.

For our team, this means that a dev or outside contributor has done work off of a feature branch, and is ready for the lead developer for a certain environment to review their code and merge it into the environment’s release branch for an upcoming deployment.

A PR (pull request) is submitted through Bitbucket, and relevant info about the request is included along with commit messages and specified branches (see more below). The lead developer reviews the request and either requests additional changes be made, or approves the request and completes the merge process.

The development branch

In order to do work on any of the environments listed above, you’ll want to set up a local environment on your machine. See more in this article.

Once you local environment is set up, you’ll need to set up a tracking branch for the development branch. The development branch is a continuous branch that exists on all environments and is kept up to date with all releases, like the master branch.

However, the development branch is never deployed. It is used as a staging area for pull requests to see how they interact and to determine if any bugs need to be fixed before work is collectively merged into a release branch for deployment.

Setup process

Use the following steps as a guide for how you can set up a development tracking branch, create your own feature branch to work on, and then submit a PR when your work is ready for review:

1. Make sure your local environment is set up, and its origin remote points to the Bitbucket repo for that environment.

2. Set up or update the development branch:

   1. Create a new development tracking branch:

      git fetch && git checkout development

   2. Or, update your existing development tracking branch:

      git fetch && git pull development

3. Once your development branch is up to date with its counterpart on Bitbucket, create a new feature branch off of the development branch.

   1. If you are working on a Jira ticket, start the branch name with CMS-<ticket number> and add a brief description, so you can keep track of multiple working branches if the need arises.

4. Do the work you need to do.

5. Once you’re done, push your work and the branch you made to origin:

   git push origin feature/CMS-1234-your-branch-name

6. Now that your feature branch is on Bitbucket, you can submit a pull request!

How to submit a PR

After completing step 6 above, you can submit a pull request. To do so, go to the repository for the site you’re working on in Bitbucket, and select Pull Requests in the left-hand menu:

Open

At the top right, click “Create pull request”. This screen will appear:

Open

Be sure to adjust the branch dropdown menus in the two boxes that are next to each other. Your feature branch should be selected in the left-side box, and the development branch should be selected in the right-side box.

Continue to add info about your request, what changed, and any details about the commits that might not be apparent from your commit messages.

Note that for this example, no changes were made to the testing branch. In practice, you will see the commits made on your feature branch below the “Create pull request” blue button when you scroll down.

Add any attachments that might be relevant, and then add reviewers (registered Jira users only). These people will be responsible for reviewing your PR and merging the code.

Once you’re ready, click “Submit pull request”!

For reviewers

If you are a reviewer for a pull request, here are the steps you can take to check the submitter’s work and help determine whether it is ready for a merge.

1. Make sure your own local environment is set up and up to date.

2. Make sure that your own local development branch exists and is up to date with origin.

3. Pull down the feature branch submitted in the request to your local site:

   1. First, checkout the development branch:

   2. Next, create a remote tracking branch of the feature branch for the PR:

Once you have a local tracking branch, you should have a copy of all the work the requester submitted as part of their PR.

Here are some general guidelines to follow when looking at a requester’s work:

• Check the site’s front end as if you were a user. Does everything work as expected? Are there any font or styling issues on pages relevant to this request? Make sure to check the site incognito (or clear your cache) to fully capture any CSS/JS changes that might be part of the request.

• Check responsiveness. Resize your browser window to see if the site behaves as expected across screen sizes.

• Check the console. Are there any unexpected errors? Toggle between development and the feature branch to help verify if something is being caused by the new code in this PR.

• Check for any PHP errors or warnings that might be caused by the new code. You can temporarily remove the debug settings from your wp-config.php file. One or more of these lines should be removed in order to see PHP warnings/errors:

• Recompile the minified CSS stylesheet if needed. In your terminal, navigate into the theme’s root directory and run gulp scss to recompile all SCSS partials into a new stylesheet.

• Check for things that work, but could be done better: unnecessary inline styling, excessive JS, and code that is generally not DRY (Don’t Repeat Yourself).

Once you’re satisfied that the code is as good as it can be for this request, you can move to the approval process.