Best Practices for Pull Requests

TIPS FOR YOUR INTERNSHIPS AND NEW GRAD POSITIONS - 2024 EDITION There are some things you learn better once the roles are reversed: I learned the importance of a good pull request (PR) once I started reviewing them myself. Here is a checklist you can refer to: 1. Getting your work reviewed doesn't shift the responsibility of catching issues to your reviewers. The prime responsibility of ensuring your work is defect-free and won't cause problems in prod is always on you, the author. The code review process is a guardrail, but don't treat it as a crutch: 'I'll have a senior engineer review my work, so I don't have to worry about testing the edge cases, they'll catch those.' This is the wrong mentality to create a PR with. If all your PRs involve reviewers pointing out edge cases, you're not doing your job diligently. 2. Document your PRs properly. Provide context, and don't take this for granted. Just because someone reviews your PR doesn't mean they'll have the complete background. Include the WHAT, WHY, and HOW. WHAT: Provide background on the issue. Example: this PR fixes an uncaught exception (include details about the exception). WHY - Why is this fix necessary? Example: the fix is needed because it helps prevent the app from crashing unexpectedly because of the uncaught exception. HOW - Example: It's fixed by encapsulating this block of code within a try-catch and logging the error. 3. Add instructions on how to reproduce the error and verify the fix locally. 4. For UI changes, including screenshots of before and after can be helpful. 5. Add tests! You'd be surprised how often this step is forgotten. 6. Keep the PR small, so it's easy to review. The usual guideline is less than 250 lines of code per PR. If it's too large, break it down into multiple PRs. 7. Review it first yourself. You'd be surprised by how many print statements you'll find that you forgot to clean up. 8. Assign the right reviewers. 9. Call out things you want to bring specific attention to, and you can cc specific people. 10. You don't have to necessarily agree with every piece of feedback provided - if there's something you feel strongly about, feel free to discuss it. If the discussion is getting too long, consider switching to a different medium - my goto is to jump on a quick call. 11. Give people enough time to review large PRs. If you're planning on merging a big feature on Friday afternoon (which isn't a great idea to begin with), don't create the PR on Thursday evening. There can be exceptions to this rule, but rushed reviews should be avoided. In the worst case, keep in mind that your PR could be reverted, which is why keeping the PR detailed is necessary. Got any more suggestions? Drop them in the comments below! #softwareengineering #technology

100 lines of code: reviewed in 10 minutes. 1000 lines of code: reviewed never. Code reviews exist to catch bugs, improve maintainability, and help teams write better software together. But most engineers treat them like assignments to pass instead of collaborative checkpoints. That mindset kills the process before it starts. ➧ When you're submitting a PR: 1. Keep it small Aim for 10-100 lines of code per pull request. Past 100 lines, reviewers start skimming. Past 500, they stop caring entirely. Large PRs are harder to review, take longer to approve, and make it nearly impossible to catch real bugs. Break your work into isolated, logical chunks. Yes, it's more work upfront. But it ships faster. 2. Write a description Give context. Always. Your reviewer might be on a different team, in a different timezone, or new to the codebase. Don't make them guess what you're solving. If you're fixing a bug, explain what broke and link to the ticket. If it's a visual change, add before/after screenshots. If you ran a script that generated code, paste the exact command you used. Context turns a confusing diff into a clear story. 3. Leave preemptive comments If part of your diff looks unrelated to the main logic, explain it before your reviewer asks. "Fixed a typing issue here while working on the main feature." "This file got reformatted by the linter, no logic changes." These small clarifications save back-and-forth and show you're thinking about the reviewer's experience. ➧ When you're reviewing a PR: 1. Be overwhelmingly clear Unclear comments leave people stuck. If you're making a suggestion but don't feel strongly, say it: "This could be cleaner, but use your judgment." If you're just asking a question, mark it: "Sanity check, is this intentional? Non-blocking, just curious." Over-communicate your intent. Especially with remote teams or people you don't know well. 2. Establish approval standards with your team Decide as a team when to approve vs. block a PR. At Amazon and now at Nielsen, we approve most PRs even with 10+ comments because we trust teammates to address feedback. The only exception: critical bugs that absolutely can't go to production. Without clear standards, people feel blocked by style comments and approvals feel arbitrary. Talk to your team. Set the rules. Stick to them. 3. Know when to go offline Some conversations don't belong in PR comments. If the code needs a major rewrite, if there's a design disagreement, or if you're about to write a paragraph, stop. Ping your teammate directly. Have a quick call. Save everyone time. Leave a comment like "Let's discuss this offline" so they know you're not ignoring it.

Growing as an engineer: Write small pull requests At my first job, we didn’t do code reviews at the beginning, and later one when the company started to do review, my code was still not reviewed because I was the only person working on frontend/node.js code. When I started at Google, the first pull request I sent (or changelist as it’s called at Google) was about 3000 lines of code. It took a few days to get approved and maybe just 2-3 passes, but looking back – it wasn’t the best way to proceed. I just didn’t know as I never reviewed code before and never had to have my code review. Sending code to be reviewed is similar to having a discussion about your project. You have to structure your presentation – first give context/problem, then describe at a high level the solution and finally go deep into each section one by one. The way to achieve this with code changes are: - Write a clear description of your code change (the context, what your change is doing, what are the follow PRs coming up, what are the risks etc.) - Break down your changes into chunks that a person can easily process – someone can easily understand a high level skeleton, or a detailed but short-ish implementation. It’s very hard for someone to parse a multi-thousands line code change. The interesting thing is that you will likely be able to merge your code faster by sending X small PRs rather than one massive one even if you’ll need more interactions with the reviewers – your reviewer will just take significantly more time to review your massive PR. The drawbacks of large PRs don’t stop here though: - The review you’ll get for a massive PR will less thorough as people will dread doing it and may skim over some parts - You will waste more time if changes are needed – e.g. if your approach wasn’t good, you have to discard more work than if you had sent just a skeleton - Getting your code in production might take more time because your changes will likely trigger more pre-merge tests (since more code is being changed) and in case a rollback is needed, you will have to roll forward more code (and maybe deal with more merge conflicts) Sending human reviewable changes is a useful skill to have – it’s one of the little things that you never have a chance to learn about at school. Bonus: Interesting illustration based on the prompt "cartoon of a software engineer breaking a change in small pieces"

I've reviewed 1,000+ pull requests. This paradox is real. The uncomfortable truth: We're terrible at reviewing large changes. Our brains literally give up. What happens with big PRs: – Reviewers skim instead of reading carefully – Focus shifts to obvious syntax issues and missed architectural problems – "LGTM" becomes the default response to avoid spending 2+ hours – Critical business logic bugs slip through unnoticed – Technical debt compounds because no one catches design flaws The psychology: Large diffs create "review fatigue." After 400+ lines, your brain switches to pattern matching instead of critical thinking. Real solution most teams ignore: – Break features into 100-200 line chunks – Review business logic separately from UI or API changes – Use draft PRs for early architectural feedback – Set team limit: No PR over 300 lines without exceptional justification The cost: That 500-line "looks fine" PR? It probably contains 3-5 bugs that will surface in production and 2-3 design decisions you'll regret in 6 months.

Git Pull Request Workflow 0. 𝐒𝐭𝐚𝐫𝐭 𝐰𝐢𝐭𝐡 𝐚 𝐂𝐥𝐞𝐚𝐧 𝐒𝐥𝐚𝐭𝐞 ➟ Before beginning any work, ensure your local repository is synced with the latest code from the remote main branch. git checkout main git pull origin main ➟ Create a descriptive branch for your feature or fix git checkout -b feature/add-user-authentication ➟ Use a clear, consistent naming convention for branches (e.g., feature/, bugfix/). 1. 𝐌𝐚𝐤𝐞 𝐋𝐨𝐠𝐢𝐜𝐚𝐥, 𝐀𝐭𝐨𝐦𝐢𝐜 𝐂𝐨𝐦𝐦𝐢𝐭𝐬 ➟ Develop your feature or fix in small, logical chunks. ➟ Each commit should address a single, meaningful unit of work. git add src/auth/ git commit -m "Ticket 1234: implement JWT token generation" 2. 𝐏𝐮𝐬𝐡 𝐘𝐨𝐮𝐫 𝐁𝐫𝐚𝐧𝐜𝐡 𝐭𝐨 𝐑𝐞𝐦𝐨𝐭𝐞 ➟ Once you’ve completed your local changes, push your branch to the remote repository. git push -u origin feature/add-user-authentication ➟ Create a pull request (PR) through your Git platform (e.g., GitHub, GitLab, Bitbucket). Include: - A clear title summarizing the change. - A detailed description explaining the purpose, implementation, and potential impacts. - Links to related tickets, issues, or documentation. - Screenshots or videos for UI/UX changes. 3. 𝐂𝐨𝐝𝐞 𝐑𝐞𝐯𝐢𝐞𝐰 𝐏𝐫𝐨𝐜𝐞𝐬𝐬 ➟ Automated Checks - CI/CD pipeline should run tests, linting, and static analysis to validate the code. ➟ AI augmented Feedback - Tools like CodeRabbit can provide immediate, context-aware suggestions for: - Code style inconsistencies. - Common bugs or anti-patterns. - Security vulnerabilities. - Performance optimizations. ➟ Human Review - Teammates should evaluate: - Architecture and design. - Maintainability and scalability. - Alignment with business logic and requirements. - Adherence to coding standards. Tip: ➬ Encourage open, constructive discussions during reviews. ➬ PRs are an opportunity to collaborate and improve, not a battleground. 4. 𝐊𝐞𝐞𝐩 𝐘𝐨𝐮𝐫 𝐁𝐫𝐚𝐧𝐜𝐡 𝐔𝐩 𝐭𝐨 𝐃𝐚𝐭𝐞 ➟ Keep your feature branch synced with the target branch (e.g., main) to avoid conflicts later. 5. 𝐅𝐢𝐧𝐚𝐥 𝐏𝐫𝐞-𝐌𝐞𝐫𝐠𝐞 𝐂𝐡𝐞𝐜𝐤𝐥𝐢𝐬𝐭 ➟ Before merging your PR, ensure the following - ✅ All CI checks pass (tests, linting, builds). ✅ Required approvals are obtained from reviewers. ✅ All review comments are addressed with follow-up commits. ✅ Documentation is updated (e.g., README, API docs). ✅ The branch is up to date with the target branch (perform a final rebase if necessary). 6. 𝐌𝐞𝐫𝐠𝐞 𝐭𝐡𝐞 𝐏𝐑 ➟ Choose the appropriate merge strategy based on your team’s workflow - - Squash Merge [Combines all commits into one for a clean history.] - Rebase Merge [Maintains a linear history while preserving individual commits.] - Merge Commit [Creates a merge node, preserving the full commit history.] ------- Remember, A good PR isn’t about showing how much you’ve done, it’s about making it easier for someone else to understand and build on your work. 🤗 #git

I've reviewed 1000+ pull requests. Here's what separates great engineers from the rest. It's not cleverness. It's clarity. 1/ Write the "why" in your PR description. What problem does this solve? Spending two minutes here saves your team 20 minutes of confusion. 2/ One change per PR. When you bundle refactoring with new features, reviewers can't tell what matters. Split them. 3/ Comment on decisions, not code. Don't explain what getUserById() does. Explain why you chose this approach over alternatives. 4/ Test the edge cases. What happens when the API is down? When the list is empty? Great engineers think through failure modes. Clever code gets you noticed. Clear code gets merged, deployed, and trusted. This kind of thinking is what I help engineers develop into a tech lead. Weekly insights in my newsletter. Link is 👆

💡 𝟳 𝗧𝗶𝗽𝘀 𝗳𝗼𝗿 𝗖𝗿𝗲𝗮𝘁𝗶𝗻𝗴 𝗘𝗳𝗳𝗲𝗰𝘁𝗶𝘃𝗲 𝗣𝘂𝗹𝗹 𝗥𝗲𝗾𝘂𝗲𝘀𝘁𝘀 ✅ Well-crafted PRs keep projects moving forward smoothly. Follow these tips to create PRs that actually get reviewed and approved quickly: - ➕ Make small, targeted changes instead of huge 1000+ line PRs that are hard to review - 📝 Add a descriptive title and clear description explaining the changes so reviewers understand the context - 🔗 Link to any related issues or supporting documentation to provide background - 🖼️ Include screenshots and gifs to demonstrate the changes rather than just describe them - 👥 Tag reviewers and request feedback from teammates to get eyes on the PR faster - ✅ Include a test plan to verify your changes and give confidence they won't break things - 🚀 Describe the deployment strategy and rollout plan so reviewers understand the impact - 🤔 Add context on why the changes are needed and their impact to justify the effort What tips do you have for creating effective pull requests? Share in the comments - let's help each other improve! #dev #programming #softwaredevelopment #pullrequests

Ever had a bunch of small changes pile up into lots of commits for just a couple of files? 📄📄 I recently faced this situation in an older PR where there were about 10 commits for tiny changes spread out over two months. Now, you might wonder, is it cool to have so many commits for just a little stuff? After thinking about it, the answer is pretty simple: having a clean and clear Git history is super important. When the code changes are related but scattered over time, squashing those commits into one coherent message can make a world of difference. 🚀 The benefits are impressive: ✅ Clean Commit Tree: A concise history is easier to navigate, review, and understand. ✅ Clarity: The purpose and context of changes become crystal clear. ✅ Streamlined Releases: A refined history ensures smoother deployments and rollbacks. 🚀 Here's how: Steps: Spot Related Commits: Identify the commits that go hand in hand. Terminal Time: Open your terminal or Git Bash. Rebase Interactively: Use git rebase -i HEAD~n, 'n' being the number of commits. Edit Mode: Change pick to squash (or 's') for commits you want to squash. Update Commit Message: A new message window appears – edit it to summarize all changes. Save and Push: Save, close, then git push -f origin branch-name. The result? A single, concise commit that captures the essence of all those changes. 🌟 #git #reactjs #pullrequest

Post 23: Real-Time Cloud & DevOps Scenario Scenario: Your team uses GitOps to manage Kubernetes clusters. Recently, a direct configuration update bypassed the review process, causing production pods to crash. As a DevOps engineer, your task is to strengthen GitOps workflows to prevent unreviewed or incorrect changes from affecting production. Step-by-Step Solution: Enable Mandatory Code Reviews: Require pull requests (PRs) for all configuration changes. Enforce approval policies where at least two team members review and approve PRs before merging. Use Branch Protection Rules: Protect the main branch by restricting direct pushes. Example (GitHub Settings): Require PR approvals. Require passing CI/CD checks before merging. Enable status checks for linting, formatting, or validation. Implement Automated Configuration Validation: Use tools like kubeval, kubernetes-schema-validator, or OPA Gatekeeper to validate Kubernetes manifests for syntax and policy compliance during the CI phase. Example CI pipeline snippet: bash Copy code kubeval my-deployment.yaml Use Progressive Delivery Strategies: Integrate canary deployments or blue-green deployments to apply changes incrementally and monitor their impact before full rollout. Enable Git Commit Signing: Require signed commits to ensure the authenticity of changes. Example (Git CLI): bash Copy code git commit -S -m "Signed commit message" Integrate Rollback Mechanisms: Use GitOps tools like ArgoCD or FluxCD with rollback features to revert to the last known good configuration in case of failure. Example (ArgoCD CLI): bash Copy code argocd app rollback my-app 2 Monitor Changes in Real Time: Set up alerts for configuration drift or failed deployments using tools like Prometheus, Grafana, or GitOps-native monitoring tools. Train Team Members: Conduct regular training sessions on GitOps workflows and Kubernetes best practices. Share lessons learned from past incidents to build a culture of continuous improvement. Use Namespace Isolation: Isolate workloads in different namespaces for staging, testing, and production environments. This minimizes the blast radius of incorrect updates. Regularly Audit GitOps Workflow: Periodically review your GitOps processes and tools to identify gaps and improve workflows. Outcome: Strengthened GitOps workflows prevent unreviewed changes from causing disruptions.Enhanced team collaboration and automated validations improve deployment reliability. 💬 How do you ensure safe and reliable GitOps workflows? Share your insights and experiences in the comments! ✅ Follow Thiruppathi Ayyavoo for daily real-time scenarios in Cloud and DevOps. Together, we innovate and grow! #DevOps #GitOps #Kubernetes #CI_CD #CloudComputing #InfrastructureAsCode #ConfigurationManagement #RealTimeScenarios #CloudEngineering #LinkedInLearning #careerbytecode #thirucloud #linkedin #USA CareerByteCode

This used to land in my inbox at least once every week: A massive pull request that feels like deciphering an ancient scroll. We've all been there. The mindset of "I'll just push all these changes together" can lead to unforeseen complications down the road. The challenges: - Navigating through endless lines of code. - Overlooked bugs because... it's just too much. - Days spent on reviews, when it could've been hours. Why small PRs win every time: 1. Efficiency: Quicker to review and approve. 2. Clarity: Each change can be understood at a glance. 3. Agility: Faster iterations, faster merges. Aim for compact, concise, and crystal-clear pull requests. It not only benefits you but your entire team. Remember, it's about quality, not quantity.