Submitting pull requests for approval

As you develop new applications and features on VA.gov, you will need to have your code reviewed by Platform engineers. The pull request review process helps maintain code quality and stability.

Resources to Get You Started

• Understand how we use GitHub code owners

• Review pull request best practices

What Constitutes an Urgent PR Review

All Pull Requests submitted to the Platform Support Team are reviewed within 24 hours. If your PR review needs to be reviewed before that time period occurs, please note that your PR is Urgent. PRs are Urgent if they are directly Veteran impacting (i.e. Veterans can not log into accounts, etc.)

Note: If you have a PR that is dependent upon a tight turn around time or a specific deadline, we recommend submitting your PR as soon as it is ready to ensure that you receive an approval in time to meet said deadline.

PR Request Sizing

We recommend that each PR is no longer than 500 lines of code. If your PR is greater than this size, we recommend breaking it up into digestible pieces. This will ensure that we are able to get to your PR within our 24 hour policy.

Note: PRs larger than 500 lines of code may be sent back to you to divide or your review may take longer than 24 hours.

What We Look for When We review Your Code

When Platform engineers do pull request reviews, here are some of the things we're looking for:

• Correctness: Does the code correctly implement the described feature?

• Code quality: Is the code readable? Is the code language-idiomatic?

• Visual changes: are screenshots of the change(s) included?

For more tips, see Pull request best practices.

Before You Submit a Pull Request

A Pull Request will not be added to the review queue until all criteria below is met:

1. A team member is required to review and approve your pull request

2. All required checks need to pass

   1. If you are having trouble passing your checks, Platform Support can help

3. The Platform Support Team cannot see Jira tickets

   1. You need to put your Jira information in the PR body in the form of a screenshot, by copying and pasting the info, or bt making a GitHub issue to link

How to Submit a Pull Request for Platform Review

1. Create a Draft pull request and have your team review it.

2. Resolve issues flagged by automated code checks. Unresolved issues may block your code from being merged.

3. Mark your pull request as Ready for Review and wait for a Platform engineer to review your code. (Code is reviewed within 24 business hours.)
   Note: For frontend PRs, the additional automated checks can trigger a review from the frontend-review-group, even for code owners.

4. Resolve all review comments from the Platform engineer.
   Note: Once the Pull Request is resubmitted with changes, 24 business hour time period restarts.

5. Merge PR into main branch for deployment.

If your team is using code owners, your code goes through automated checks, but might not be reviewed by a Platform engineer. See How we use GitHub code owners for more information.

After a pull request is submitted

This is the process that happens after someone submits a pull request:

1. After a request for a PR review is submitted to the #vfs-platform-support channel, Tier 1 support is alerted.

2. A Tier 1 Support Team Member acknowledges the PR for review in the #vfs-platform-support with an 👀 emoji.

3. That ticket populates in ZenHub.

4. A Tier 1 Support Team Member goes into Zenhub and assigns the ticket to themselves.

5. The Tier 1 Support Team Member ensures that the request for review is at least 24 hours old. If the request for review is not at least 24 hours old, the Tier 1 Support Team Member waits until the request for review is 24 hours old.
   

   

6. The Tier 1 Support Team Member checks if a second person on the same team as the person who created the PR has reviewed this PR already.

   

7. The Tier 1 Support Team Member checks who the code owner is for the PR. The code owner is a team. This code owner information will also show if this is a Frontend PR or a Backend PR or a DevOps PR.

   

8. The Tier 1 Support Team Member ensures that all template filler text in the PR has been removed. If there is still filler text remaining, the Tier 1 Support Team Member asks the person who created the PR to remove the filler text. In the example below, the highlighted areas show where filler text still remains.

   

9. The Tier 1 Support Team Member finds and reads the section in the PR where it explains how this change will impact the Platform.

   

10. The Tier 1 Support Team Member ensures that the changes have already been tested. Here’s how to do this:

    1. The Tier 1 Support Team Member navigates to the “Files Changed” section on the PR in Github, as seen in the example below.

    2. The Tier 1 Support Team Member looks for where the path is highlighted, as seen in the example below. This lets the Tier 1 Support Team Member know that the change has been tested.
       

       

       1. For backend PRs, the Tier 1 Support Team Member looks for a path that contains “spec.”

       2. For frontend PRs, the Tier 1 Support Team Member looks for a path that contains ”unit.spec.jsx” or “cypress.spec.js.”
          

          

11. The Tier 1 Support Team Member ensures that all required checks are passing. Here’s how to do this:

    1. The Tier 1 Support Team Member navigates to to the “Checks” tab in the PR, as seen in the example below.
       

       

    2. If any checks failed, the Tier 1 Support Team Member asks the person who created the PR to ensure all checks are passing. To make all checks pass, the person who created the PR may need to edit their code.

       

12. In Slack, the Tier 1 Support Team Member responds to the person that created the PR, writing “Hello, thank you for reaching out, <end user>!”

13. In Slack, the Tier 1 Support Team Member reaches out to either Frontend Tier 2 Support, Backend Tier 2 Support, or DevOps Tier 2 Support, depending on if this is a Frontend PR, a Backend PR, or a DevOps PR. Checking who the code owner is in Step 7 determines which type of PR this is. The Tier 1 Support Team Member asks Frontend/Backend/DevOps Tier 2 Support to review this PR, writing, “<Tier 2> can you help look at this PR? I have verified the required checks are passing and are older than 24hrs.”

14. In Slack, the Tier 2 Team Member acknowledges and approves the message with a ✅ emoji when it’s completed.

15. In Slack, the Tier 1 Support Team Member marks the ticket with :Support_Complete: emoji, which closes the ticket.
    

    

     

Here’s an example of a real PR and the changes it made:

• In the originating issue, you can see that the purpose of this PR is to “rename forms api module to simple forms api,” thus changing “forms_api” to “simple_forms_api.” This change was made because the Lighthouse Team has an API named “Forms API.” The Lighthouse Team asked to change the name of their forms so there is no confusion.

• For a broader scope of understanding the request, you can view the GH ticket in the link above.

• You can see the acceptance criteria in the image below. The criteria is addressed with this PR.
  

  

FAQ

Help and feedback

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.