Skip to main content
Skip table of contents

Submitting pull requests for approval

Last Updated:

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

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 turnaround 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 by 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.

A slack thread in which a pull requested is submitted

A pull request being submitted for review via #vfs-platform-support

  1. That ticket populates in ZenHub.

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

A Zenhub board with a PR ticket

The ticket populating in Zenhub with the assignee

  1. 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.

    A note saying that someone requested a review yesterday, which means that the request for review is 24 hours old.

    This says that a person requested a review yesterday, which means that the request for review is 24 hours old.

  2. 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.

    A PR that shows that John Doe created the PR and that Jane Dory, who is John Doe's team member, reviewed the PR

    Here you can see that John Doe created this PR and Jane Dory, who is on Joe’s team, reviewed the PR.

  3. 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.

    A PR that shows that VA Platform Cop Frontend is the code owner

    The code owner for this PR is VA Platform Cop Frontend

  4. 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.

    A PR with filler text still inside it that needs to be removed

    In this PR, filler text is still there. It needs to be removed.

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

    A PR with a section that explains how the change will impact the Platform

    In this section, the person who created the PR explains how the change will impact the Platform.

  6. 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.

      A PR showing that the changes have been tested

      Here you can see changes that have 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.”

        A PR that contains code that contains the phrase 'unit.spec.jsx'

        This example is a frontend PR that contains the phrase ”unit.spec.jsx.”

  7. 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.

      A PR with checks that failed

      This specific PR example shows that some checks failed.

    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.

      A PR with checks that passed

      The confirmation that checks are passing

  8. 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>!”

  9. 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.”

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

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

    A slack thread showing a Tier 1 Support Team Member reaching out to a Tier 2 Team Member and getting approval

    A Tier 1 Support Member reaching out to a Tier 2 Team Member and getting approval.

     

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.

    The acceptance criteria for a specific PR

    This is the acceptance criteria for a specific PR.

FAQ

I created a pull request and I meant to create a draft pull request instead. How do I change it to a draft pull request in GitHub?

Underneath the list of reviewers, there's text that says "Still in progress? Convert to draft" and the Convert to draft text is a link to change the PR to a draft.

What do I do if my pull request receives a warning or is rejected because it is too large?

Review your code and decide if you can make two or more smaller, focused pull requests. See Pull request best practices for tips. For help with reducing the size or coordinating a larger review, reach out in Slack. Expect that reviewing a large pull request will take extra time.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.