Skip to main content
Skip table of contents

Best Practices for Writing Pull Requests

Last Updated: November 26, 2024

As you develop new applications and features on VA.gov, your code will need a review from Platform engineers to ensure quality and stability.

To help your PR reviews proceed smoothly and promptly, please follow our best practices for writing pull requests. For detailed guidance on submitting PR requests, refer to this article: Submitting Pull Requests for Approval.

1. Plan accordingly

  • Ensure that you have planned enough time to meet your deadlines and have accounted for the review time in that timeline (average of 3 business days to review a PR)

  • Note: We can not guarantee a PR can be pushed through due to lack of planning.

2. Review applicable documentation

We recommend reading through the following documentation prior to submitting PR reviews:

3. Make PRs clear

  • Give your PR a title that sums up what's changed.

  • Describe the changes so reviewers know what they're looking at.

  • Link to any related GitHub issues for context.

  • Clearly outline how to test the change (not just locally) and what the expected results are.

4. Break down tasks

  • Don't bite off more than you can chew. Break big tasks into smaller, more manageable ones.

  • For example, when building a new page, tackle it step by step:

    • Set up the page structure.

    • Add in each component one by one.

  • This way, each part gets proper attention without overwhelming anyone.

5. Mitigate PR size

  • Keep your PRs compact, aiming for less than 500 lines of code.

  • It makes reviews quicker and easier for everyone involved.

  • If your PR is too big, offer extra help to reviewers:

    • Point out important changes.

    • Be available for a quick chat to explain things.

    • Write detailed descriptions to guide reviewers.

6. Branch smart

  • Start a new branch for each feature you're working on.

  • Create a PR for each sub-branch, using the main branch as the base.

  • It keeps things organized and makes merging smoother.

7. Stay on track

  • Stick to the task at hand. Focus on solving the issues in your ticket.

  • It makes reviews smoother and saves time for everyone.

8. Note if a PR is urgent (only if actually urgent)

  • All Pull Requests submitted to the Platform Support Team are reviewed within 1 business day of the PR being ready for review (tests passing, etc.).

  • If your PR review needs to be reviewed before that time period occurs, please note that your PR is Critical

    • Examples of critical issues include:

      • A bug that’s preventing a significant number of Veterans from accessing a feature

      • A bug creating a non-trivial deviation from expected functionality

      • A 508/accessibility failure of severity level 0 (Showstopper) or 1 (Critical) (severity rubric)

      • A PR needs to be merged to unblock other developers.

        • Example: A form schema update in another repo was merged, but the corresponding code changes need to be merged as well, otherwise there will be test failures in CI for other devs.

      Examples of non-critical issues include:

      • Incorrect text or visual formatting that does not impede the feature from working

      • Any code for features not yet released to Veterans

      • Just wanting to get code out sooner

      When in doubt on whether an issue is critical enough for out-of-band deployment, OCTO-DE leadership for the Platform will decide.

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.

9. Help your reviewers

The Platform Support Team looks for the following standards when reviewing PRs. Meeting these standards could ensure a quicker review:

  • 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?

10. Mind your style

  • Run your code through a linter before submitting a PR.

  • If you ignore a linting recommendation, explain why in the PR comments.

  • Fix any unrelated issues separately.

11. Use drafts wisely

  • If your PR isn't ready for review, mark it as a draft.

  • This stops premature notifications and gives you time to polish things up.

12. Meet PR requirements before setting to ready for review

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.

Note: If you have not met these requirements, there may be a delay in the review of your PR.

13. Wait 3 business days before sending a ticket asking for an update

Our engineers review queues multiple times a day, and all reviews are completed within 3 business days. Submitting a ticket before this period may delay PR reviews. If it's been longer than 3 business days, please reach out to the Platform Support Team for assistance.

Other resources for pull requests

How To Submit a Pull Request to Platform Support for Approval

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close