Best Practices for Publishing Pull Requests in Modern Software Teams

publishing-pull-requests.md

Introduction

Pull requests (PRs) are a cornerstone of collaboration in modern software engineering. A well-crafted PR not only merges code but also communicates context and invites engagement from reviewers. In teams building applications across React Native (mobile), Next.js (web), and Node.js (backend), clear PR communication ensures that all team members – regardless of specialty – can understand and review changes effectively. In fact, a PR’s description and structure can be as valuable as the original task specification (How to Make a Proper Description for a Pull Request). High-quality PRs save time in reviews and reduce back-and-forth clarifications, leading to faster approvals and a healthier code review culture (How to Make a Proper Description for a Pull Request).

This report outlines best practices for creating clear and effective pull requests, from writing meaningful titles and descriptions to structuring commits and using metadata. It also provides standardized PR templates for different types of work (features, bug fixes, refactors, dependency updates, etc.), and concludes with a Quick Reference Guide that engineers can use in their repositories for immediate guidance.

1. Best Practices for Crafting Clear and Effective Pull Requests

Effective pull requests focus on technical communication: they clearly explain what the change is, why it’s needed, and how to understand and test it. They also encourage engagement by making it easy for others to review and discuss the changes. Below, we break down the key best practices:

Meaningful Titles and Descriptions

• Use Descriptive, Specific Titles: The PR title is the first thing reviewers see, so it should succinctly describe the change. Avoid one-word or overly broad titles (e.g. "Update code"); instead, be specific about the impact. For example, instead of "Fix bug", a clear title would be "Fix login button unresponsive issue on Safari", which immediately tells the team what was addressed (Best practices for writing clear pull request titles and descriptions). Similarly, "Update CSS" is vague, whereas "Refine grid layout for better mobile responsiveness" is much more informative (Best practices for writing clear pull request titles and descriptions). If your team uses ticket IDs, include them for traceability (e.g. "Add search functionality – Closes #123") (Best practices for writing clear pull request titles and descriptions).
• Write in Imperative Mood: Follow the style of commit messages by using imperative verbs (e.g. “Add,” “Fix,” “Remove”) in the title (Best practices for writing clear pull request titles and descriptions). For instance, "Remove deprecated API endpoint" is preferred over "Removing deprecated API endpoint" – this establishes a consistent, action-oriented tone.
• Start Descriptions with a Summary: Begin the PR description with 1-2 lines summarizing the change and its purpose (Best practices for writing clear pull request titles and descriptions). This “elevator pitch” helps reviewers grasp the high-level goal immediately. For example: “This PR introduces a new caching layer to improve response times for user profile requests.”
• Provide Context and Rationale: The description should explain why the change is needed and any background that is not obvious from the code. Link relevant resources such as issue reports, design documents, or prior discussions (Best practices for writing clear pull request titles and descriptions). This ensures that even someone who isn’t deeply familiar with the specific context (e.g. a backend engineer reviewing a React Native UI change) can understand the motivation. As one guide notes, a PR description effectively serves as documentation of your thought process, including rationale for implementation choices and any challenges or decisions made (How to Make a Proper Description for a Pull Request) (How to Make a Proper Description for a Pull Request).
• Break Down the Changes: Rather than a wall of text, use bullet points or small paragraphs to enumerate the major changes in the PR (Best practices for writing clear pull request titles and descriptions). Each bullet can explain a specific change or group of changes, ideally answering "what was changed and why." For example:
  • Refactored authentication logic to simplify token handling.
  • Introduced caching for user profiles to decrease load times.
  • Fixed edge case where user session did not expire properly.
    This structured approach guides the reviewer through the code by grouping related modifications, which saves them from mentally clustering the diffs themselves (The (written) unwritten guide to pull requests - Work Life by Atlassian). The PR author, having all details fresh in mind, is best positioned to highlight these conceptual groupings for the reviewer (The (written) unwritten guide to pull requests - Work Life by Atlassian).
• Explain the “How”: If not evident from the code, briefly describe how the solution is implemented. This might include mentioning new classes or functions and their purpose, or noting algorithmic choices. Keep it concise—focus on important logic, not every trivial detail (the diff itself shows the code). If the code changes were discussed elsewhere or alternatives were considered (e.g. different libraries or approaches), summarize those discussions and reasoning in the PR (or include a "Premise" section as some templates do) (How to Make a Proper Description for a Pull Request) (How to Make a Proper Description for a Pull Request). This preempts questions like "why did you do it this way?"
• Include Testing Instructions: Provide clear steps for how to test or verify the changes (Best practices for writing clear pull request titles and descriptions). List any setup needed, scenarios to run through, or specific commands. For instance, “To test this PR: run npm start, navigate to the Profile screen in the iOS simulator, and verify that the updated avatar appears after upload.” Detailing expected outcomes helps both reviewers and QA validate the changes. In the case of bug fixes, including steps to reproduce the bug (and confirming it’s resolved) is extremely helpful. Remember that reviewers might not be as familiar with the feature or environment, so guiding them reduces friction. One guideline suggests treating the PR description like a mini user manual for the code change (Authoring Pull Requests | Compass by Nimble) – it should be possible to understand and test the update without digging elsewhere.
• Use Visual Aids for UI Changes: When the changes affect the user interface or visual output, attach screenshots or short GIFs/videos in the PR description (The (written) unwritten guide to pull requests - Work Life by Atlassian). “Make it visual” is a proven way to speed up understanding for front-end changes (The (written) unwritten guide to pull requests - Work Life by Atlassian). Seeing the before/after UI states or an animation of the new feature can save reviewers time and provide confidence in how the feature looks. For example, a React Native UI tweak might include screenshots of the app screen on Android and iOS after the change. (For back-end changes in Node.js, equivalently you might include a sample log output or API response to illustrate the effect.) As Atlassian’s guide notes, it’s easier to reason about front-end changes when you can visually see what has been changed (The (written) unwritten guide to pull requests - Work Life by Atlassian). Including designers or product stakeholders in such PRs can also be beneficial, as they might catch UI/UX issues early (The (written) unwritten guide to pull requests - Work Life by Atlassian).
• Declare Scope and Limitations: If the PR does not address certain related issues or is part of a larger feature, mention that to set the right expectations. For example, “This PR focuses on the login flow and does not include changes to the sign-up flow (to be handled in a separate PR).” Explicitly noting out-of-scope items or future work helps avoid confusion (Best practices for writing clear pull request titles and descriptions). It’s also good to mention any known follow-up tasks (e.g., “will add unit tests for edge cases in a subsequent PR”) so reviewers know if something is intentionally left out.
• Keep the Description Updated: As the PR evolves (through code review feedback or new discoveries), update the description accordingly. A well-maintained description that reflects the final state of the PR ensures the PR remains a useful reference even after merging.

Well-Structured Commits for Clarity

A pull request is composed of one or more commits, and how those commits are structured can greatly affect reviewability. Commits should tell a clear story of the development progress:

• One Logical Change per Commit: Strive to have each commit represent a single coherent change or idea (The Art of a Well Composed Pull Request | by Zoe Larsen | FAUN — Developer Community ). This makes it easier for reviewers to follow the progression of changes and understand the purpose of each commit. Avoid commits that mix unrelated modifications (for example, refactoring code style in the same commit as adding a new feature). Instead, if you updated a user controller, a helper function, and a UI component for a feature, consider splitting those into separate commits for each area (The Art of a Well Composed Pull Request | by Zoe Larsen | FAUN — Developer Community ). Conversely, if you made the same type of change across many files (e.g., renaming a variable in ten files), batching those in one commit is acceptable (The Art of a Well Composed Pull Request | by Zoe Larsen | FAUN — Developer Community ). The goal is to make commits modular and focused.
• Commit Narratively: Organize commits in a sequence that makes logical sense (e.g., for a feature, perhaps commit the model changes first, then the controller logic, then the UI, etc.) (The Art of a Well Composed Pull Request | by Zoe Larsen | FAUN — Developer Community ). This isn’t always strictly necessary, but a sensible order (such as “backend API change” commit followed by “frontend integration” commit) can help reviewers understand dependencies. It creates a narrative of how the solution was built up.
• Informative Commit Messages: Just like PR titles, commit messages should be clear and meaningful. The first line of the commit message should be a brief summary of the change, written in present-tense imperative (for example, “Add caching layer for profiles”). In the commit body, if the change is not self-evident, you can add a sentence or two explaining why the change was made (The Art of a Well Composed Pull Request | by Zoe Larsen | FAUN — Developer Community ). Good commit messages can serve as a built-in changelog for the PR, giving reviewers a “bullet point” summary of code changes (The (written) unwritten guide to pull requests - Work Life by Atlassian). They also help future maintainers understand the history. Avoid empty or cryptic messages like “fix stuff” or the notorious “Address PR feedback” – these don’t add value for reviewers (The (written) unwritten guide to pull requests - Work Life by Atlassian).
• Separate Refactoring Commits: If you needed to refactor or reformat code as a prerequisite to your main change, consider isolating that in its own commit. For example, if you renamed variables or restructured files to make the feature easier to implement, put those changes in a commit distinct from the one adding new functionality. This separation is very helpful: reviewers can first examine the refactor commit (which should have no functional changes), then focus on the commit that introduces new behavior (Why Pull Requests Alone Won't Give you a Good Code Review Culture - James Ridgway). James Ridgway, in discussing code review practices, advises splitting refactoring from behavior changes where possible (Why Pull Requests Alone Won't Give you a Good Code Review Culture - James Ridgway). It reduces noise in the diffs and clarifies what’s a pure cleanup versus a substantive code change.
• Ensure Each Commit Builds & Passes Tests: Ideally, each commit in the PR should leave the repository in a working state (tests passing, app running). This isn’t a strict rule in all teams, but it’s a good practice that enables options like using git bisect to pinpoint issues later. It also means a reviewer could check out any single commit to test just that part. Keeping commits build-safe reinforces that they’re logically complete pieces.
• Squash or Retain Commits as Appropriate: Some teams prefer to squash commits when merging (resulting in a single combined commit in the main branch), while others keep the commit history. If the latter, ensure your individual commits are tidy and meaningful. If you know commits will be squashed, you still benefit from structuring them during review, but you might not need to obsess over minor fix-up commits as those can be squashed away. However, even in a squash-merge workflow, it’s courteous to clean up obviously irrelevant commits (like multiple “typo fix” commits) by amending or rebasing before merge, so that the interim noise doesn’t distract reviewers.

Providing Relevant Context, Screenshots, and Testing Information

A pull request should be self-contained in terms of understanding the change. Always aim to preempt reviewers’ questions by providing context and evidence upfront:

• Background and Motivation: In the description (or a dedicated “Background” section), include any essential background. For a new feature, briefly describe the user story or requirement. For a bug fix, describe the problem that was occurring and its root cause. Reviewers should not have to dig through issue trackers or commit history to piece together why this PR exists – spell it out for them (How to Make a Proper Description for a Pull Request) (How to Make a Proper Description for a Pull Request). If the PR relates to a discussion or design document, link it. For example: “This change implements the new authentication flow as discussed in [Design Doc X] (Best practices for writing clear pull request titles and descriptions).
• Link Issues and Tickets: Use keywords to link the PR to issue IDs (e.g., using GitHub’s “Closes #ISSUE” syntax) so that related issues are automatically referenced (How to Make a Proper Description for a Pull Request). This not only provides context but also helps update the issue status when the PR is merged. If multiple issues or tasks are relevant, list them (e.g., a “Related Tasks” list) (How to Make a Proper Description for a Pull Request). This practice ensures traceability: anyone looking at the PR can easily find the original requirements or bug report.
• Show Before-and-After (for UI changes): When fixing a bug or adding a feature that changes behavior or appearance, showing the state before vs. after is incredibly useful. For UI changes, include a screenshot of the old UI (or describe it) and one of the new UI. If fixing a visual bug on a Next.js web page, for instance, you might include a screenshot of the page rendering incorrectly and another with the fix applied. For React Native mobile features, consider attaching a short video or GIF demonstrating the new behavior (e.g., a new navigation flow or a fixed animation glitch). This visual context allows reviewers (and QA or designers) to validate the change immediately (The (written) unwritten guide to pull requests - Work Life by Atlassian). It’s often said that a picture is worth a thousand words – in PRs, a screenshot can be worth a hundred-line code review.
• Logs or Examples (for non-UI changes): For backend or logic changes where screenshots don’t apply, provide other evidence of correctness. This could be example outputs from a Node.js API endpoint, log excerpts showing a job running successfully, or shell output from a test case. For instance, “After the fix, the service returns a 200 OK with response: {...} (shown in the attached log excerpt).” Such context is analogous to screenshots, but for data/logic – it helps reviewers see the effect of the code in a real scenario.
• Testing and Verification Steps: As noted earlier, clearly instruct how to test the PR. If the team relies on manual QA, enumerate steps for them. If automated tests are included, mention what areas the tests cover (e.g., “Added unit tests for the new caching logic”). In a cross-platform project (mobile/web/backend), be explicit about any testing needed on each platform: e.g., “Tested on Android emulator and iOS device for React Native app, and ran npm test for the Node backend changes.” This gives reviewers confidence that the change works as intended across the stack. Notably, including thorough testing info in the PR can reduce review cycles – the reviewer might catch if a scenario is untested, or they might feel more comfortable approving knowing the author tested all relevant cases.
• Include Screenshots of Test Results (if useful): If you have run unit tests or integration tests that produce a report, you might screenshot or copy the relevant part of the report (or include a badge/status from CI). This is optional, but for visual regression tests or snapshot tests, for example, showing “All tests passed” or a diff of coverage can reinforce the PR’s readiness.
• Highlight Important Implementation Details: If there are parts of the code that deserve special attention during review (complex algorithms, important decisions, tricky third-party library usage), mention these in the description. For example, “Note: The parsing logic in Parser.js is performance-critical; feedback on the approach is welcome.” This guides reviewers on where to focus and invites specific discussion, increasing engagement.
• Ask for Specific Feedback: Don’t hesitate to call out anything you’re unsure about. A PR is also a request for comments. If you have concerns about a particular approach or would like a careful review of a certain area, mention it. For instance, “I’m not entirely confident about the error handling in the payment service – reviewers, please pay extra attention to that part.” By explicitly soliciting feedback, you signal that you welcome input, which encourages reviewers to engage more deeply. It’s better to mention these in the PR description (or a dedicated “Concerns” section) rather than leaving reviewers to guess (How to Make a Proper Description for a Pull Request). This openness can lead to productive discussions and collective problem-solving during review.

Effective Use of Labels, Tags, and Metadata

Beyond the core description, modern code platforms (GitHub, GitLab, etc.) allow adding metadata to PRs. Utilizing these effectively can streamline the review process and improve engagement:

• Tag the PR Type: Apply labels to indicate the category of the change, such as feature, bugfix, refactor, documentation, chore, etc. This categorization is especially useful in multi-disciplinary teams. For example, a label like frontend or mobile vs. backend can signal who might want to review (a Next.js expert for a frontend PR, a Node.js specialist for a backend PR). Many teams use labels to filter PRs in dashboards or to trigger automation. A consistent labeling scheme helps everyone identify the nature of a PR at a glance (Authoring Pull Requests | Compass by Nimble). For instance, Nimble’s engineering guidelines categorize PRs by type (feature, bug, chore) and priority using labels (Authoring Pull Requests | Compass by Nimble).
• Use Labels for Workflow and Priority: Labels like WIP (Work in Progress) or do-not-merge can indicate that a PR is not ready for full review yet, which prevents premature approvals. On the other hand, a label such as urgent or a high-priority marker can signal reviewers that a PR needs quick attention. Complexity labels (like size: large) are another example some teams use to indicate review effort required (Improving Pull Request Process with Complexity Labels | by Sigute) (Best Practices for Using GitHub Issues - Rewind Backups). Use these labels judiciously to route the PR to the right reviewers and timeline.
• Leverage PR Templates and Metadata Fields: If your repository has multiple PR templates (for different types of changes), make sure to select the appropriate one when creating the PR (or use automation to apply it). The template will often prompt you to fill out sections like “Breaking Changes” or “Dependencies” – don’t skip these. Filling out all relevant fields in a template (e.g. checkboxes for testing completed, or notes about migrations required) ensures no important information is omitted. It also shows reviewers that you have thought through deployment implications, which builds confidence.
• Assign Reviewers and Assignees: A PR left unassigned can fall through the cracks. Always assign appropriate reviewers – at least one peer engineer and, if possible, a tech lead or domain expert for that area of the code (Authoring Pull Requests | Compass by Nimble). For example, if the PR touches mobile code, include a React Native lead; if it’s a build script update, maybe assign a DevOps engineer. Adding multiple reviewers (e.g. two is a common practice (Authoring Pull Requests | Compass by Nimble)) increases the chances of a timely review and diverse feedback. Also consider using code owners or auto-assign bots for relevant paths, so the PR automatically requests reviews from the right people. In addition, setting yourself (the author) or a project manager as the assignee can clarify who is responsible for shepherding the PR to completion.
• Milestones and Projects: If your team uses milestones (e.g., for a version or sprint) or project boards, attach the PR to the relevant milestone or project. This gives context about when the change is targeted to be released and ties the work into broader timelines. It’s a form of metadata that keeps the PR connected to planning artifacts.
• Link CI/CD Results: Ensure your PR is linked to continuous integration checks (this is usually automatic on platforms like GitHub if you have set up CI). A green check from tests and linters can encourage reviewers to engage, knowing that the basics are passing. If a test is failing and it’s a known issue not caused by your PR, mention that in the description or comments to avoid confusion.
• Use Draft PRs for Early Feedback: If you want engagement before the code is final, mark the PR as a Draft (available on GitHub) or add a "WIP" label. This signals reviewers that you’re seeking input on an approach without asking for a full approval yet. It can be a great way to get design-level feedback or unblock questions early. However, still provide a description and context even for draft PRs – clarify what you’re looking for feedback on.

Avoiding Common Pitfalls that Reduce PR Engagement

Even with good intentions, certain patterns can make pull requests less inviting to reviewers or cause delays in the review process. Be mindful to avoid these pitfalls:

• Overly Large Pull Requests: A PR that is too big (touching many files or thousands of lines) can overwhelm reviewers. Changes that are broad or combine multiple tasks are hard to digest, leading to reviewer fatigue (Why Pull Requests Alone Won't Give you a Good Code Review Culture - James Ridgway). As a result, reviewers may procrastinate or only skim parts of the code, increasing the chance that issues slip through. Large PRs also tend to have more merge conflicts if they sit open for long. To keep engagement high, break large changes into smaller, focused PRs whenever possible (The ultimate guide to pull request guidelines). As one guide puts it, making small, logical PRs might be harder upfront, but it greatly eases and speeds up the review (The (written) unwritten guide to pull requests - Work Life by Atlassian) (The ultimate guide to pull request guidelines). A good rule of thumb is to limit PRs to a few hundred lines or a single feature/fix – enough to provide context but not so much as to drown in detail (The ultimate guide to pull request guidelines). If a PR must be large (e.g., a sweeping refactor), mitigate by providing an exceptionally clear description and maybe splitting the commits for easier review.
• Vague or Missing Descriptions: A PR with a title like “Misc fixes” and no description is likely to be ignored or bounced back to the author for clarification. Insufficient description forces reviewers to read every line of code to infer intent, which is frustrating (How to Make a Proper Description for a Pull Request). It also invites misunderstanding. Always fill in a description, even if the change seems “obvious” to you. Remember, what’s obvious to the author may not be to others. Lack of context in PRs is a top complaint among reviewers, as it wastes time and can lead to misinterpreting the purpose of changes (How to Make a Proper Description for a Pull Request) (How to Make a Proper Description for a Pull Request). Make it a habit to never publish a PR without at least a few sentences of explanation.
• Mixing Unrelated Changes: Combining multiple unrelated fixes or features into one PR (“while I was in the area, I also updated the UI color and fixed an unrelated bug”) can confuse the review. It’s better to separate concerns: each PR should have one primary focus (The ultimate guide to pull request guidelines) (Why Pull Requests Alone Won't Give you a Good Code Review Culture - James Ridgway). Unrelated changes in a single PR make it hard to assign the PR to the right reviewers (different expertise might be needed for different parts) and complicate the discussion. If the PR grows beyond its initial scope, consider carving out the extra changes into follow-up PRs. In particular, do not bundle cosmetic refactors with functional changes – as noted earlier, split them so that reviewers can discern pure refactoring from logic modifications (Why Pull Requests Alone Won't Give you a Good Code Review Culture - James Ridgway).
• Poor Commit Hygiene: Dozens of WIP commits or fix-up commits like “update 1”, “update 2”, or “typo fix” can signal a lack of preparedness. While it’s fine during development, before requesting a review it’s good to squash or rebase to clean up trivial commits. A messy commit history in the PR can make it harder for reviewers who try to read commit by commit. Moreover, commit messages that don’t correspond to the final code (due to changes later) can be misleading. Take a moment to polish the commit history if your team’s process allows – it shows professionalism and respect for the reviewer’s time.
• Not Engaging with Reviewers: After creating the PR, a common pitfall is “fire and forget” – not actively monitoring and responding to reviewer comments. This can drastically reduce engagement; reviewers might lose interest if their feedback sits unanswered. To avoid this, be responsive: answer questions, clarify doubts, and make requested changes promptly (or discuss them). A lively, respectful discussion in the PR comments often signals a healthy review. On the flip side, avoid being defensive – remember the goal is to improve the code together. If the PR author is welcoming and collaborative, reviewers will be more inclined to participate.
• Lack of Supporting Material: Sometimes PRs involve changes that require additional context like performance benchmarks, screenshots, or logs, as discussed. Neglecting to include these when needed can reduce reviewer confidence. For example, if you claim a change improves load time, showing a before/after benchmark in the description will engage reviewers and preempt skepticism. If such evidence is missing, reviewers might leave comments asking for it, which delays the process.
• Skipping the PR Template/Checklist: If your repo has a PR template with checkboxes (e.g., “Tests added”, “Docs updated”), do not ignore it. Skipping sections (like leaving “Testing instructions” empty) can hint at corners cut. It may cause reviewers to doubt if you tested thoroughly or considered documentation. Always either complete each section or, if not applicable, explicitly state so (e.g., “Documentation: N/A”). This demonstrates diligence and makes the reviewer’s job easier – they don’t have to ask “did you test this on iOS?” if you’ve already checked the “Tested on iOS” box.
• Unclear Impact or Risk: Failing to mention if a change is backward-compatible, behind a feature flag, or has a potential migration impact is a pitfall that can reduce engagement because it leaves reviewers guessing about risk. Always communicate the impact: for instance, if a Node.js API change might break clients, say so and mention how to mitigate it. If the PR includes a database migration, highlight that and perhaps mark the PR with a migration label. Reviewers are more comfortable approving when they fully grasp the implications of a merge. If they aren’t sure, they may hold off or ask many questions.
• Neglecting Documentation and Follow-up: Sometimes code changes require updating documentation (README, API docs, etc.) or have follow-up tasks (like updating config in production). Not addressing or mentioning these can lead to incomplete work. It’s a best practice to include doc changes in the same PR for a feature, or at least note if documentation will be updated elsewhere. Forgetting this can be seen as a miss, and a reviewer then has to flag it, which could have been avoided.

By being aware of these pitfalls and addressing them proactively, you make your pull requests far more reviewer-friendly. The goal is to maximize understanding and minimize the effort required from others to give meaningful feedback. In summary, think of a PR as a communication artifact: you’re not just delivering code, you’re delivering context and confidence along with it. When done well, a PR can even “sell” your change to the team – making reviewers enthusiastic about merging it (The (written) unwritten guide to pull requests - Work Life by Atlassian)!

2. Standardized Pull Request Templates by Type of Work

Having standardized PR templates helps ensure that every pull request contains the essential information in a consistent format. Instead of relying on memory each time, a template provides prompts for the author to include all relevant details. This is especially useful for a team working on multiple projects (mobile, web, backend) where consistency helps everyone review each other’s code seamlessly. Notably, templates should be based on the nature of the work (feature, bug fix, etc.) rather than the tech stack – the structure of good communication is universal, whether it’s a React Native component or a Node.js API change.

Using PR templates brings several benefits: it enforces a uniform review process, clarifies expectations up front, and saves time by reducing repeated back-and-forth on what information to provide (GitHub pull request template | Axolo Blog). It also improves overall code quality by ensuring crucial items (like testing steps or documentation updates) are not overlooked (GitHub pull request template | Axolo Blog). Below, we present recommended PR templates for common types of changes. These templates are structured as sections with guidance on what to include in each. Teams can adapt them as needed, but the core sections aim to cover the key information for each scenario.

Template: Feature Development PR

Purpose: Used for new features or enhancements that add functionality. This template ensures the new feature is well described, justified, and tested.

Suggested Sections to Include:

• Title: A short descriptive title of the feature (often using a format like “feat: [area] what the feature does”). If applicable, include a ticket or issue ID. Example: “feat: Profile – add avatar upload capability”.
• Summary/Description: A brief overview of the feature and why it’s being added. This should mention the user story or problem being solved. For example: “Adds the ability for users to upload a profile picture. This fulfills the requirement of user story #45, allowing richer user profiles.” Keep it high-level here; details will come later.
• Details of Implementation: Explain the approach taken. Break this into bullet points or short paragraphs for subcomponents of the feature:
  • UI/UX changes: Describe any new screens or components (for React Native/Next.js, mention which screens or pages are affected). Include screenshots of new UI elements or state changes if relevant.
  • Backend changes: If the feature required backend work (e.g., new API endpoint in Node.js or changes in database), summarize those changes. E.g., “Added /api/profile/upload endpoint to handle image uploads (Node.js service)”.
  • Architecture/Design decisions: Note any important decisions or alternatives considered. For instance, “Chose to use AWS S3 for storing images for scalability – considered storing in DB but opted against due to size concerns.” Provide reasoning especially if the decision might be non-obvious.
• Dependencies: List any new dependencies or libraries introduced (e.g., “Added react-native-image-picker library to handle image selection”). Also mention if any dependencies were upgraded as part of this feature. This alerts reviewers to look at license, size, or compatibility of new libs.
• Testing Instructions: Provide clear steps for testing the feature end-to-end. For example:
  1. Navigate to the Profile screen in the app.
  2. Tap on the avatar placeholder – the image picker should open.
  3. Select an image, then verify that a preview is displayed and a success message appears.
  4. On the backend, verify that the image file appears in the cloud storage bucket and the database record is updated with the image URL.
     Include any specific environment setup needed (like API keys or feature flags). Also, mention if you wrote automated tests (unit/integration) and how to run them (npm test, etc.).
• Screenshots/Media: If UI changes are part of the feature, include screenshots or a short video. E.g., Before and after screenshot of the profile page with and without an avatar. This gives reviewers immediate visual context. For a purely backend feature, you might include a screenshot of a successful API call in a tool like Postman, or logs that show the feature working.
• Documentation: Note if any documentation was updated or needs updating. For example, “Updated the README with instructions on configuring image storage.” If docs changes are included in the PR, point to them; if not, mention how documentation will be handled (to ensure it’s not forgotten).
• Issue Link(s): Reference the user story or issue tracking this feature (using keywords to auto-close if applicable). For instance: “Closes #123” or “See JIRA ticket APP-45 for more details.” This ties the PR to the original requirement and lets reviewers see full context if needed.
• Checklist: (Optional) A checklist of common things to verify for features, for example:
  • Unit tests added/updated
  • Documentation updated (if applicable)
  • Localization strings added (if this is a user-facing text change)
  • No console warnings or errors introduced (for front-end features)
    This helps ensure the author has double-checked these important aspects before review.

Rationale: This structured template ensures a feature PR tells a complete story: the what, why, and how of the new functionality. It emphasizes showing the impact on UI and API (especially important in React Native/Next.js/Node contexts where a feature might span front-end and back-end). It also prompts the author to consider tests and documentation. By following this template, the PR becomes a one-stop reference for the feature’s design and usage, making the reviewer’s job much easier.

Template: Bug Fix PR

Purpose: Used for fixing bugs or issues. The template highlights reproducing the bug, the solution, and verification that the fix works.

Suggested Sections to Include:

• Title: Include the word “fix” or “bug” and a brief description of the problem. For example: “fix: Crash on login when password field is empty”. If there’s a bug ID or issue number, include it (e.g., “Bug #410 – fix crash on empty password”).
• Problem Description: Describe the bug in detail. Explain what was happening, where/when it occurs, and its impact. For instance: “When a user attempts to log in without entering a password, the app throws a null pointer exception and crashes. This is affecting the React Native login screen on both Android and iOS.” If the bug is environment-specific (only in Safari, only in production mode, etc.), note that. Providing context such as when the bug was introduced (if known, e.g., “regression in v1.2.0”) can also be useful.
• Root Cause Analysis: Briefly explain the cause of the bug as determined by investigation. For example: “The crash was caused by the login function not handling an undefined password field – the API call was still attempted with password: undefined, causing a type error in the backend.” If relevant, mention how you identified the cause (for instance, referencing a specific log or using a debugger). Keeping this section concise is fine; the goal is to show you understand why the bug happened.
• Solution Description: Explain the fix implemented. This should map to the code changes made. For example: “Added a check on the client side to disable the login button and show an error if password is empty. Also added validation in the Node.js backend API to return a 400 error if password is missing, to handle any edge cases.” If you considered other solutions, you can mention why the chosen fix is the best. If the fix has any side effects or implications, note them (e.g., “Now disallows empty passwords, which was previously not explicitly handled – this is an improvement in validation.”).
• Verification Steps: Provide step-by-step instructions to reproduce the bug and verify that it is fixed with this PR. For example:
  1. On the login screen, leave the password field empty and click “Login”.
  2. Expected: the app should not crash. Instead, it should show a validation message “Password is required” and stay on the login screen.
  3. You can also test entering a password to ensure normal login still works.
  4. Test both on Android and iOS (React Native) and also verify that making a direct API call to /login without a password returns a proper error response instead of a server exception.
     If possible, include a screenshot of the error message or logs after the fix (e.g., a screenshot of the validation message on the app). This helps demonstrate the issue is truly resolved (The (written) unwritten guide to pull requests - Work Life by Atlassian).
• Affected Areas: Mention if this bug fix touches multiple parts of the system. For example, “This affects only the mobile app’s login component, no changes to backend logic except input validation.” Or “Impacts the Next.js web login page and the shared auth API.” This context is useful for reviewers to know if they need to test elsewhere or consider broader implications.
• Regression Tests: Note any tests added or updated to catch this bug in the future. E.g., “Added a unit test for the auth reducer to ensure it handles empty passwords gracefully.” If no automated test is added, consider adding a checkbox in a checklist (like “[ ] Added regression test”) to signal whether this was done. Reviewers often look for this to ensure the bug doesn’t reappear.
• References: Link the issue or bug report (e.g., “Fixes #410”). If the bug was discussed in Slack or an email thread, and if it’s appropriate to do so, you might link to a summary or relevant excerpt. Any external reference (stack overflow, etc.) that helped solve the bug can be linked here as well for additional context.
• Checklist: Common items:
  • Reproduced the issue on dev/QA environment
  • Verified the fix on dev/QA environment
  • Added/updated tests (if applicable)
  • Checked that no new lint or type errors are introduced
  • Considered security implications (especially if the bug was a security issue) and updated threat models if needed.

Rationale: This template ensures that anyone reading the PR can understand the bug without having been there. It forces the author to articulate the problem and the fix, which leads to better-informed reviews. It also helps QA to validate the fix by following the same steps. In a tri-platform team (mobile/web/backend), explicitly noting the impacted platforms ensures the right testers verify the fix in all necessary environments (e.g., a bug might appear on mobile but not web). By documenting the root cause and solution clearly, the PR also becomes a knowledge resource for the team – if a similar bug appears, one can look back at this PR for insight.

Template: Refactoring / Code Cleanup PR

Purpose: Used when no new feature is added and no bug is directly fixed, but code is restructured for clarity, performance, or maintainability. The key here is to communicate that behavior remains equivalent (if that’s the case) and why the refactor is worthwhile.

Suggested Sections to Include:

• Title: Include “refactor” or “cleanup” and mention the scope. For example: “refactor: Simplify state management in Settings screen” or “cleanup: Remove unused API endpoints”. This makes it clear it's not introducing new features.
• Goal/Purpose: Explain why this refactor is being done. Possible reasons: improving readability, performance, reducing technical debt, preparing for a future feature, etc. E.g., “Simplify the settings state management by using Redux Toolkit to reduce boilerplate and improve maintainability. This is in preparation for upcoming features that will expand settings options.” If the refactoring addresses code smells or issues (like a SonarQube finding or a TODO comment), mention that as the motivation.
• Scope of Changes: Describe what is being refactored or restructured. Break it down by area if multiple components are affected:
  • “Converted class components to functional components with hooks in the React Native Settings screen.”
  • “Extracted common utility functions from utils.js into separate modules.”
  • “Optimized the database query for fetching user data to use the new index on users table.”
    Use bullet points to list major code changes, but emphasize that these are internal changes. If there’s no intended change in functionality, state that explicitly (reviewers love to see “No functional changes” up front, as it frames their review to focus on code quality rather than new behavior). For example: “No user-facing changes – all existing unit tests pass, indicating behavior is unchanged.”.
• Before vs After (if relevant): If the refactor changes how something is done under the hood, it can be useful to illustrate the difference. For instance, show a snippet of old approach vs new approach in the description if it aids understanding. Or describe a performance improvement: “Previously, loading the dashboard made 5 separate API calls; now it’s consolidated into 2 calls, reducing load time (tested via profiling to be ~30% faster).” Even though it’s not a feature, this helps reviewers appreciate the benefit.
• Testing and Verification: Even if functionality shouldn’t change, outline how you verified that nothing broke: e.g., “Ran full test suite – all tests still pass.”, “Manually tested all settings toggles on both iOS and Android to ensure they still work as expected.”. If the refactor is significant, suggest specific areas for focused testing (like “Because the auth logic was refactored, testers should verify login/logout flows still behave identically, including error scenarios.”). This not only guides the reviewer but also any QA folks.
• Backward Compatibility / Migration: If the refactor involves removing or changing interfaces (APIs, components) that others use, note whether there are any backward compatibility issues. For example: “Removed the deprecated legacyLogin method – confirmed it’s not used anywhere else in the codebase.” If there are migration steps (perhaps if the refactor requires a one-time data migration), clearly describe those or link to migration scripts.
• Impact on Developers: If this refactor affects the developer workflow (e.g., “Switched to a new linting rule, so developers will need to run npm install to get updated ESLint config” or “Updated directory structure; merge will require everyone to refresh their IDE project files”), highlight that. This is important in teams so that everyone is aware of changes that might affect their day-to-day work.
• Checklist:
  • All existing tests passing (and perhaps attach a screenshot of test results for confirmation)
  • Added tests for any new logic introduced by the refactor (if any)
  • Verified no regression in key functionalities (list them if needed)
  • Documentation/comments updated (if code interfaces changed or any README/changelog needs update)
  • Code is formatted and linted (especially if the refactor involved code style changes)

Rationale: Refactoring PRs can be tricky to review because there’s no new feature to manually test; the reviewer must trust that the author didn’t introduce regressions. By clearly stating the intent and that behavior should remain the same (unless otherwise noted), you help the reviewer focus on how the code changed (style, structure, efficiency) rather than what it does. Emphasizing that tests cover the changes or that you did manual checks builds confidence. The template also reminds authors to update any documentation or developer notes, which is often forgotten during pure code moves. In a multi-platform team, refactors might happen in shared code or specific platforms – calling out affected areas (e.g., “mobile only” or “backend API”) means the right people will review and test accordingly.

Template: Dependency Update PR

Purpose: Used when updating external dependencies (libraries, frameworks, packages) or tools. This template ensures transparency about version changes and any impact on the project.

Suggested Sections to Include:

• Title: Clearly state the dependency change. For example: “chore: Bump React Native from 0.68.0 to 0.70.0”, or “chore: Update axios to 0.21.4 to address security warning”. Using the format “Bump [dependency] from X to Y” is common for clarity.
• Description of Change: List each dependency being updated and the old -> new version. If multiple dependencies are updated in one PR (sometimes done in a regular maintenance sweep), itemize them:
  • Upgrade Next.js from 12.0.7 to 13.1.1
  • Upgrade react-native-firebase from 8.2.0 to 9.0.0
  • Bump Node.js runtime in Docker from 14 to 16
    For each, if available, mention why the update is done: security patch, new features, compatibility, or just routine maintenance. E.g., “Next.js 13 brings performance improvements and React 18 support”, or “Node 16 is now the LTS, upgrading to stay current.”
• Changelog / Release Notes: Provide links to release notes or changelogs for the updated dependencies, especially if it’s a major version bump. For example: “See React Native 0.70 changelog for details of breaking changes.” Summarize any breaking changes or notable changes from those notes that affect your application. This shows the reviewer you’ve done due diligence. For instance: “React Native 0.70 removed support for iOS 11; our minimum iOS target is 12, so we are fine.” or “Axios 0.21.4 fixes a prototype pollution vulnerability (The (written) unwritten guide to pull requests - Work Life by Atlassian).” If no significant changes, you can say “Minor version update, no breaking changes per release notes.”.
• Testing & Verification: Describe how you verified the application works with the new dependency versions. For example:
  • “Ran the full test suite – all tests pass.”
  • “Launched the React Native app on both iOS and Android – smoke tested login, navigation, and key features to ensure no runtime errors.”
  • “Tested the Next.js app in development and production mode to ensure no build or runtime issues after the upgrade.”
  • “Verified that all critical endpoints still function with Node.js 16 in our staging environment.”
    If the dependency update could affect production (e.g., upgrading a database or an auth library), mention any extra caution like “Will do additional load testing in staging before deploying to prod.”. This section is crucial because dependency updates, while often routine, carry the risk of breaking something indirectly.
• Backward Compatibility: Note if the update affects compatibility. For libraries, this might mean code changes were required in your project. E.g., “Updated our code to replace deprecated method X with Y due to the library update.”. If the PR includes those code changes, highlight them. If the dependency update is major and not backward-compatible, ensure that’s called out boldly (and likely such changes might merit separate PRs or careful rollout).
• Migration Steps (if any): If the update requires any migration (database migrations, config changes, re-building assets, etc.), outline those steps. For example: “Developers need to run pod install after pulling this update, because the iOS pods for React Native have changed.”, or “The environment variable FOO is replaced by BAR in the new version, updated in the .env.example and deployment configs.”. This prepares the team for any after-merge tasks.
• Related Issues: Sometimes dependency updates close security issues or fix known bugs. Mention if this PR resolves any such issue (e.g., “Closes security alert CVE-XXXX from GitHub advisories by updating lodash.”). If there was a tracking ticket for upgrading (some teams file tickets like “Upgrade to RN 0.70”), link it.
• Checklist:
  • All tests pass with new dependencies
  • Updated any code for breaking changes (if applicable)
  • Checked that build and deploy scripts (CI/CD) work with new versions
  • Informed the team of any new requirements (e.g., min Node version, new env vars)
  • Security issues resolved (if relevant) and no new warnings introduced

Rationale: Dependency changes can be mundane, but they carry risk and often are less tangible than feature changes. This template forces the author to treat an upgrade with the same rigor as a code change: reading release notes, testing thoroughly, and communicating impacts. For a reviewer, seeing this information is crucial – it answers “Have they checked what this upgrade entails?” so the reviewer can focus on anything suspicious in the diff (like changes in config files, etc.). In a cross-platform project, dependency updates might range from front-end libraries to backend modules; listing them clearly ensures that if a specialist’s input is needed (e.g., a database upgrade might need a DBA’s review), it can be routed correctly. It also fosters team awareness, as everyone will know “Oh, we upgraded library X” which might affect their local setup or future work.

Template: Other PR Types (Documentation, Chore, CI/CD, etc.)

Not all changes fall neatly into feature/bug/refactor/dependency. There are other types of PRs that affect the developer workflow or project health. Here we outline a template that can be adapted for documentation updates, build/config changes, or other maintenance chores. The idea is similar: communicate the intent and impact clearly.

Examples of such PRs: Updating a README or contributor guide, changing CI configuration (GitHub Actions, CircleCI scripts), modifying linting/formatting rules, adding a new script or tool to the project, etc.

Suggested Sections to Include:

• Title: Preface with a tag like “docs:”, “chore:”, “build:” as appropriate. E.g., “docs: Update README with setup instructions for new dev environment”, “chore: Add Prettier for code formatting”, “ci: Modify GitHub Actions to run tests on Node 16”. The title should convey the general nature of the maintenance change.
• Purpose/Overview: Explain what this change is and why. For documentation: “Updating the README to include instructions for environment setup and clarify contribution guidelines.” For a chore: “Adding Prettier to enforce consistent code style across the codebase.” For CI: “Updating CI pipeline to improve caching and reduce build time.”. Essentially, describe the problem being solved or the improvement being made for the developers or project.
• Details: Depending on the type of change:
  • Documentation: List major additions or changes. E.g., “Added section on how to run the mobile app locally.”, “Fixed outdated information about API endpoints in the docs.”. If the docs relate to a certain version or feature, mention it. You might also provide screenshots if the docs are something visual (like images in a wiki), though for text docs it’s not needed.
  • Code quality/tooling changes: Describe what’s being added or changed. “Integrated Prettier with default settings; added a pre-commit hook to format code on commit.”, “Upgraded ESLint and adjusted rules: turned off rule X, switched rule Y to warning.”. Explain any impacts on developers: “Developers should run npm install to get the new dev dependencies. After merging, everyone should format their code with Prettier – a separate PR will format the entire codebase.”. Essentially, highlight what new tool or rule is introduced and why (e.g., code consistency, catching bugs earlier, etc.).
  • Build/CI changes: Outline changes to the pipeline or configuration. “Changed Docker base image to Node 16 slim to reduce image size.”, “Added step to run mobile tests on a Firebase Test Lab for Android.”. If environment variables or secrets are involved, mention how they are handled. Note any expected outcome: “This should cut CI time from ~10min to ~6min due to caching node_modules.”.
• Impact: It’s important to state who or what is affected:
  • For documentation, the impact might be on onboarding new developers or clarifying usage for current devs. “No code impact – documentation only. Should help new team members set up the project without issues.”.
  • For dev tools or chore changes, impact is on all contributors: “All developers should adhere to the new code style; CI will fail if code isn’t formatted. Run npm run format before pushing.”. This sets expectations.
  • For CI changes, impact might be on the release process or quality: “CI will now run an extra job, so pull request checks might take 2 minutes longer, but we get integration test coverage on iOS.”. Or “No impact on product, but if CI passes it gives more confidence in mobile compatibility.”.
• Verification: Describe how to verify the change:
  • If it’s documentation, verification is simply reading and maybe following the new instructions – ensure they actually work. If you had someone test the steps, mention that (or at least that you followed them yourself in a fresh setup).
  • For tooling, perhaps include running the tool to show it works: “Ran npm run lint and ensured no errors with new config.”, “Tested the pre-commit hook locally – it correctly formats code on commit.”.
  • For CI, the proof is partly in the CI results. If the PR includes a CI config change, check that the CI passes on this PR – that serves as evidence. You might still describe any manual test of the pipeline if applicable (like running a script locally).
• Checklist:
  • For docs: Spell-checked and reviewed for accuracy
  • For tools: All developers notified of the change (maybe via team chat)
  • Updated any documentation related to this change (e.g., if adding Prettier, maybe update the README’s coding style section)
  • Verified CI/CD passes after the change
  • (If applicable) Tagged this PR with documentation or chore label for clarity

Rationale: This catch-all template is about transparency in changes that developers or processes will feel. These changes might not directly affect the product’s features, but they affect how the team works. By documenting why a chore/infra change is done, team members who might not be deeply involved in, say, CI configuration can still understand the benefit. It’s also helpful for future reference – e.g., if later on someone wonders “Why do we have this build step?”, the PR that introduced it (with a clear explanation) serves as historical context. For documentation PRs, treating them with the same seriousness as code (clear explanation of changes and purpose) encourages reviewers to give docs due attention, not just treat them as an afterthought.

---

Each of these templates is focused on the content of the change (feature, fix, etc.), not the technology used. Whether the team is working on a React Native mobile app, a Next.js web app, or a Node.js server, the fundamental questions a PR should answer remain the same. By having tailored templates, engineers are prompted to provide all information relevant to that type of change, which leads to more thorough and efficient reviews.

3. Quick Reference Guide – PR Best Practices & Templates

Below is a concise reference guide that teams can include in their repositories (e.g., in a CONTRIBUTING.md or as a cheatsheet) for quick access. It summarizes the key best practices for pull requests and provides template outlines for different PR types. This guide is formatted for easy scanning and real-world use:

PR Best Practices – Cheat Sheet ✅

• Craft Clear Titles: Use a descriptive, concise title in imperative mood (e.g., “Fix logout redirect error” instead of “Fixed stuff”). Include issue/ticket IDs if applicable.
• Write a Detailed Description: Always explain the what, why, and how of your change. Start with a one-line summary, then add context: link related issues, describe the problem and solution, and highlight important changes. The PR should be understandable without digging elsewhere.
• Keep PRs Focused and Small: Whenever possible, limit the scope of a pull request to a single feature or fix. Avoid mixing unrelated changes. Smaller PRs are faster to review and encourage engagement. If a PR starts getting too large, consider breaking it into multiple PRs.
• Structure Commits Logically: Commit your changes in logical chunks. Each commit should ideally address one topic or task. Separate refactor or formatting changes from functional changes by using separate commits. Write meaningful commit messages for each commit.
• Include Context and Evidence: Provide everything a reviewer might need to evaluate the change: screenshots or GIFs for UI updates, example outputs or logs for backend changes, and clear steps to test the changes. If the change was discussed elsewhere (issue tracker, Slack), summarize the outcome of that discussion in the PR.
• Provide Testing Instructions: Don’t assume reviewers know how to test your feature/bugfix. List step-by-step instructions or scenarios to run through. Specify any setup needed (env vars, data seeding) and what outcomes to expect. If you added automated tests, mention what areas they cover.
• Use Labels and Metadata: Apply labels for PR type (feature, bug, refactor, etc.) and any other relevant tags (e.g., frontend, backend, urgent). This categorization helps routing and filtering PRs. Mark the PR as a Draft or add a WIP label if it’s not ready for full review. Assign appropriate reviewers (and a milestone, if using) when you open the PR to prompt timely reviews.
• Avoid Common Pitfalls: Don’t open PRs without descriptions. Don’t let PRs grow too large or linger without response. Ensure you update documentation and tests in the same PR when applicable. And don’t forget to respond to reviewer comments promptly – a PR is a two-way conversation.
• Use the PR Template: Follow the project’s PR template structure. Fill out each section of the template (or note “N/A” if not applicable). The template exists to make sure nothing important is missed, from testing steps to documentation notes.

(Keep this list visible in your repository or pull request template to remind every contributor of these practices.)

Standard PR Templates – By Change Type 📋

When opening a new pull request, use the template that best matches your change. Below are outline templates for common PR types. Copy the relevant template and replace the placeholder text with details for your PR. (Each template is in Markdown format, which works on GitHub, GitLab, etc.)

Template: Feature Enhancement

## Summary
<!-- Briefly describe the new feature or enhancement and why it’s needed. -->
Adds the ability for users to ___, addressing the need for ___ (related to issue #__).

## Description of Changes
<!-- Describe what you changed to implement the feature. Break into points or paragraphs for clarity. -->
- **UI Changes:** ___ (mention any new screens or components, and attach screenshots below)
- **Backend Changes:** ___ (mention any new APIs, database changes, etc.)
- **Logic Details:** ___ (any notable algorithm or approach details, if needed)
  
## Screenshots (if applicable)
<!-- If the feature involves UI changes, include before & after screenshots or a GIF. -->
*Image or GIF demonstrating the feature in action.*

## How to Test
<!-- Provide step-by-step instructions for reviewers to test the feature. -->
1. ___ 
2. ___ 
3. ___ 
<!-- Include expected outcomes for each step. -->

## Issue Link(s)
<!-- Link to relevant user story, issue, or task. Use keywords like 'Closes #123'. -->
Closes #__

## Checklist
- [ ] Tests added or updated for new functionality  
- [ ] Docs updated (if applicable)  
- [ ] All new and existing tests pass (run `npm test` etc.)  
- [ ] Linting and formatting check passed

(Use this for new features or significant enhancements. It ensures you cover context, implementation, visuals, and testing.)

Template: Bug Fix

## Problem Description
<!-- Describe the bug: what was the issue, when/where does it occur, and its impact. -->
The application ___ (e.g., crashes, misbehaves) when ___ under ___ conditions.

## Root Cause
<!-- Briefly explain the cause of the issue, if known. -->
This was happening because ___.

## Solution
<!-- Describe your fix and how it resolves the issue. -->
Implemented ___ to fix the problem. Now, ___ (explain the new behavior or state after fix).

## How to Reproduce & Test
<!-- Steps to reproduce the bug, and then verify the fix. -->
1. **Reproduce Bug:** ___ (step by step until the issue occurs).
2. **Test Fix:** ___ (what to do now, and what you should observe with the fix in place, instead of the bug).
3. ___ (additional scenarios, e.g. test related functionality to ensure no side-effects).

*Expected result:* ___ (describe what the correct behavior/output is after the fix).

## Affected Areas
<!-- Mention parts of the app affected by the fix (feature name, component, module, etc.) -->
Impacts the ___ (module/feature). No impact on ___.

## Issue Link
Closes #__  (link to the bug report issue if one exists)

## Checklist
- [ ] Reproduced issue and verified fix manually  
- [ ] Added a regression test (if applicable)  
- [ ] No new ESLint/Type errors introduced  
- [ ] Relevant documentation updated (e.g., changelog, troubleshooting guide)

(Use this for bug fixes. It focuses on describing the issue and proving that the fix works.)

Template: Refactor/Maintenance

## Motivation
<!-- Why is this refactor or cleanup needed? -->
This refactor is intended to ___ (e.g., improve performance, improve code readability, remove tech debt, prepare for X feature).

## Changes
<!-- List what was changed or refactored. If no functional changes, state that clearly. -->
- Refactored ___ (what was changed and how).
- Removed/renamed ___ (if any dead code or renaming).
- Updated ___ (any patterns, libraries, or code style changes).

*Impact:* No expected change in behavior for end-users. (All tests passing means functionality should remain equivalent.)

## Testing
<!-- Explain how you tested that this refactor doesn't break existing functionality. -->
- Ran full test suite: all tests pass.  
- Manually tested critical flows: ___ (list a few key areas) to confirm they still work as before.  
<!-- If performance, memory usage, or other metrics are relevant, mention any improvement observed. -->

## Notes
<!-- Any additional info, such as follow-up work or known trivial issues left. -->
- Developers should ___ (e.g., run `npm install` due to updated dev dependencies, etc.).  
- (If applicable) This is part 1 of refactors; more to come in future PRs.

(Use this for pure refactoring or code cleanup changes. Emphasize that functionality hasn’t changed, and detail how you ensured nothing broke.)

Template: Dependency Update

## Dependencies Updated
<!-- List each dependency and the old vs new version. -->
- **___:** `vX.Y.Z` -> `vA.B.C`  
- **___:** `vX2.Y2.Z2` -> `vA2.B2.C2`  
*(e.g., "React Native: 0.68.2 -> 0.70.0")*

## Reason for Update
<!-- Why are we updating these? Security fix, new features, routine upgrade, etc. -->
- ___ (e.g., "Security patch for vulnerability CVE-1234" or "Needed for compatibility with Node 16").

## Notable Changes
<!-- Summarize important changes or potential impacts from the release notes. -->
- ___ (e.g., "React Native 0.70 drops iOS 10 support; our minimum iOS version is 12, which is okay").
- ___ (e.g., "Lodash 4.17.21 includes fixes for ____").

For full details, see release notes:  
- [Dependency 1 vA.B.C release notes](<link>)  
- [Dependency 2 vA2.B2.C2 changelog](<link>)  

## Testing
<!-- Describe how the application was tested with the new dependencies. -->
- Ran `npm install` and `npm run build` – build succeeds without errors.  
- All unit/integration tests pass.  
- Smoke tested the app: ___ (list key functionalities) to ensure no breakage.  
- Checked that CI pipeline passes with new versions.

## Checklist
- [ ] No new console warnings or errors introduced by these updates  
- [ ] Updated configuration or scripts if needed (e.g., CI node version)  
- [ ] Informed team of any new requirements (documentation, Slack, etc.)

(Use this for updating libraries, frameworks, or tools. It ensures everyone understands what changed and that you’ve tested the system after the update.)

Template: Documentation / Chore

## Summary
<!-- What is being changed or added in the documentation or chore? -->
Updated ___ (e.g., "README setup instructions" or "CI workflow for tests").

## Details
<!-- Provide details on the changes. For docs: outline new sections or major edits. For chores: describe config or script changes. -->
- ___  
- ___  
*(e.g., "Added a new section about environment variables", "Fixed typos in API docs", or "Added a script to automate database backup".)*

## Rationale
<!-- Why make this change? -->
- ___ (e.g., "Clarify setup steps for new developers", "Automate a repetitive task to save time"). 

## Impact
<!-- Who/what does this affect? Developers, CI process, etc. Any action needed post-merge? -->
- Documentation: No code impact, but developers should read the updated section on ___.  
- Chore/CI: Developers need to ___ (e.g., "install new tool", "note that CI now runs on node 16").  
- No user-facing impact.

## Checklist
- [ ] Proofread documentation / verified script works  
- [ ] All CI checks pass (for config/script changes)  
- [ ] Team notified of relevant changes (if any)

(Use this for changes that aren’t directly code features or fixes, such as docs and build tasks. It highlights why the change was made and any effects on the team.)

---

Using the Templates: Copy the appropriate template when creating a PR and fill in each section. Remove any sections that are not applicable, or mark them as not applicable. For example, if a bug fix has no related issue ticket, you can remove the “Issue Link” section or write “N/A”. The goal is to ensure you’ve considered each aspect, not to have empty headings.

By following these best practices and templates, our team can maintain a high standard of communication in pull requests, leading to faster reviews and more effective collaboration across React Native, Next.js, and Node.js projects. Each PR will tell a complete story about the code change, making it easier for everyone to engage with and approve with confidence.