diff --git a/Create a Good PR.md b/Create a Good PR.md new file mode 100644 index 00000000..13bb5723 --- /dev/null +++ b/Create a Good PR.md @@ -0,0 +1,114 @@ +## Table of contents + +- [Table of contents](#table-of-contents) +- [Why It Matters](#why-it-matters) +- [Before You Open Your PR](#before-you-open-your-pr) +- [What Makes a PR “Great”](#what-makes-a-pr-great) + - [1. Clear Purpose](#1-clear-purpose) + - [2. Focused Scope](#2-focused-scope) + - [3. Helpful Description](#3-helpful-description) + - [4. Show, Don’t Tell](#4-show-dont-tell) + - [5. Tested \& Verified](#5-tested--verified) +- [Common Mistakes to Avoid](#common-mistakes-to-avoid) +- [Final Checklist Before You Request Review](#final-checklist-before-you-request-review) +- [Reviewers Appreciate...](#reviewers-appreciate) +- [Need Help?](#need-help) + +This page is an introduction to creating a great Pull Request (PR). A great Pull Request (PR) is more than just code—it’s clean, clear, and easy for reviewers to understand. This guide shares best practices for writing high-quality PRs that are easy to review and quick to merge. + +## Why It Matters + +A good pull request isn’t just about working code—it’s about making collaboration easier. Clear, well-structured PRs save reviewers time, reduce confusion, and help maintain high code quality. In open source, thoughtful PRs build trust and keep the project maintainable for everyone. + +For the essential checklist and best practices, be sure to follow [Rules for making PRs](./rules-for-making-prs.md)—every good PR starts there. + +## Before You Open Your PR + +Make sure you’ve: + +- Created a branch off the latest `develop` +- Pulled the latest code: `git pull upstream develop` +- Tested your changes locally +- Passed all relevant tests +- Cleaned up your code (no stray debug logs or commented code) +- Written a fix plan (if required) and got it approved + +## What Makes a PR “Great” + +Here’s what makes a PR stand out: + +### 1. Clear Purpose + +Use a **descriptive PR title** and mention the issue number. + +**Good:** +`Fix #4567: Align navbar correctly on small screens` + +**Bad:** +`Update UI stuff` + +### 2. Focused Scope + +- Stick to **one topic per PR** +- Don’t sneak in unrelated changes +- Keep your PRs small when possible—**smaller PRs are faster to review** + +### 3. Helpful Description + +Fill out the PR template completely: + +- What did you change? +- Why was it needed? +- Any tricky parts? +- Screenshots for UI changes +- Questions you want feedback on + +### 4. Show, Don’t Tell + +If your PR changes the UI, **include before-and-after screenshots**. This helps reviewers instantly understand the visual impact. + +### 5. Tested & Verified + +Before requesting review: + +- All tests pass (unit, integration, lint) +- You've tested manually (especially for UI or logic changes) +- Edge cases are handled + +## Common Mistakes to Avoid + +| ❌ Don’t Do This | ✅ Do This Instead | +|------------------|--------------------| +| "Fix some stuff" in title | "Fix #1234: Add padding to dashboard cards" | +| Combine unrelated fixes | Separate into focused PRs | +| Skip writing a description | Clearly explain what and why | +| Add unfinished code | Only push code that’s ready | +| Forget screenshots | Add visual proof for UI changes | + +## Final Checklist Before You Request Review + +- [ ] My PR addresses **one issue only** +- [ ] I followed **Oppia’s code style** +- [ ] All **tests pass** +- [ ] I filled out the **PR template** +- [ ] I included **screenshots** (if needed) +- [ ] My commit message is clear and formatted +- [ ] I pushed the **latest code** +- [ ] I’m ready to **respond to reviews** promptly + +## Reviewers Appreciate... + +- Clean, readable code +- Clear commit history +- Context provided in comments if something’s non-obvious +- Respect for their time + +## Need Help? + +Don’t be afraid to ask! You can: + +- Tag reviewers in comments +- Use [GitHub Discussions](https://github.com/oppia/oppia/discussions) + +Thanks for taking the time to make your PR shine. +High-quality PRs make Oppia better for everyone! diff --git a/_Sidebar.md b/_Sidebar.md index 7e0489a2..a70ffd7e 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -24,14 +24,15 @@ * Team onboarding guides * [[LaCE Team|LaCE-onboarding-guide]] * [[Contributor Dashboard Team|Contributor-dashboard]] + * [[Learning resources for developers|Learning-Resources]] * [[How the codebase is organized|Overview-of-the-Oppia-codebase]] * Making your first PR * **[[Good first issues|https://github.com/oppia/oppia/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22]]** - * [[Finding the commit that introduced a bug|How-to-find-the-commit-which-introduced-a-bug]] * [[Tips for finding the right code to change|Find-the-right-code-to-change]] + * [[Finding the commit that introduced a bug|How-to-find-the-commit-which-introduced-a-bug]] * [[Tips for analyzing the codebase|Analyzing-the-codebase]] - * [[Learning resources for developers|Learning-Resources]] - * [[Rules for making PRs|Rules-for-making-PRs]] + * **[[How to create a good PR|Create a Good PR]]** + * [[Rules for making PRs|Rules-for-making-PRs]] * [[Coding style guide|Coding-style-guide]] * [[Debugging|Debugging]] * [[Debugging Docs|Debugging-Docs]]