From 3df411b8a8a15e8c60e304abe030751b02d6ac3c Mon Sep 17 00:00:00 2001
From: LittleRain <98176228+LittleRainC@users.noreply.github.com>
Date: Mon, 28 Apr 2025 08:36:18 -0400
Subject: [PATCH 1/5] Add "Create a Good PR" file

---
 Create a Good PR.md | 99 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 Create a Good PR.md

diff --git a/Create a Good PR.md b/Create a Good PR.md
new file mode 100644
index 00000000..b7166b38
--- /dev/null
+++ b/Create a Good PR.md	
@@ -0,0 +1,99 @@
+# How to Craft a Great Pull Request
+
+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
+
+Contributing code is awesome—but making it **easy to review** is just as important. A thoughtful PR saves time for reviewers, avoids misunderstandings, and helps Oppia maintain a high standard of quality.
+
+## 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
+- Ask in Oppia’s chat or community channels
+
+Thanks for taking the time to make your PR shine.  
+High-quality PRs make Oppia better for everyone!

From 8eeaa1227fb659e3f47e5e5132231e4176532ce0 Mon Sep 17 00:00:00 2001
From: LittleRain <98176228+LittleRainC@users.noreply.github.com>
Date: Mon, 28 Apr 2025 08:53:35 -0400
Subject: [PATCH 2/5] Update _Sidebar.md

add "Create a Good PR" under "Making your first PR"
---
 _Sidebar.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/_Sidebar.md b/_Sidebar.md
index 7e0489a2..a5484725 100644
--- a/_Sidebar.md
+++ b/_Sidebar.md
@@ -32,6 +32,7 @@
       * [[Tips for analyzing the codebase|Analyzing-the-codebase]]
     * [[Learning resources for developers|Learning-Resources]]
     * [[Rules for making PRs|Rules-for-making-PRs]]
+      * [[Create a Good PR|Create a Good PR]]
       * [[Coding style guide|Coding-style-guide]]
   * [[Debugging|Debugging]]
     * [[Debugging Docs|Debugging-Docs]]

From 48f6f1977c1bb5b13a5334fe221d9baf1472716d Mon Sep 17 00:00:00 2001
From: LittleRain <98176228+LittleRainC@users.noreply.github.com>
Date: Mon, 28 Apr 2025 09:16:37 -0400
Subject: [PATCH 3/5] Update Create a Good PR.md

Add table of content part
---
 Create a Good PR.md | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/Create a Good PR.md b/Create a Good PR.md
index b7166b38..843b7bfd 100644
--- a/Create a Good PR.md	
+++ b/Create a Good PR.md	
@@ -1,6 +1,20 @@
-# How to Craft a Great Pull Request
-
-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.
+## 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
 
@@ -17,7 +31,7 @@ Make sure you’ve:
 - 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”?
+## What Makes a PR “Great”
 
 Here’s what makes a PR stand out:
 

From 1b77d8f3992e2451fbc06c65c90e4357395c0001 Mon Sep 17 00:00:00 2001
From: LittleRain <98176228+LittleRainC@users.noreply.github.com>
Date: Thu, 1 May 2025 00:28:23 -0400
Subject: [PATCH 4/5] Update _Sidebar.md

Moved the learning resources for developers to the "getting started" section above. Adjusted the structure of makings PRs.
---
 _Sidebar.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/_Sidebar.md b/_Sidebar.md
index a5484725..a70ffd7e 100644
--- a/_Sidebar.md
+++ b/_Sidebar.md
@@ -24,15 +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]]
-      * [[Create a Good PR|Create a Good PR]]
+    * **[[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]]

From d16a84718c783c7c805f3f49e781972a55cda976 Mon Sep 17 00:00:00 2001
From: LittleRain <98176228+LittleRainC@users.noreply.github.com>
Date: Thu, 1 May 2025 01:39:48 -0400
Subject: [PATCH 5/5] Update Create a Good PR.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. Added space between "Pull Request" and "(PR)" in first sentence
2. Added a refer to the more detailed "PR guide" at some point
3. Used a checklist format - [ ]
4. Linked the relevant github discussions category
5. Removed the "Ask in Oppia’s chat or community channels".
---
 Create a Good PR.md | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/Create a Good PR.md b/Create a Good PR.md
index 843b7bfd..13bb5723 100644
--- a/Create a Good PR.md	
+++ b/Create a Good PR.md	
@@ -14,11 +14,13 @@
 - [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.
+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
 
-Contributing code is awesome—but making it **easy to review** is just as important. A thoughtful PR saves time for reviewers, avoids misunderstandings, and helps Oppia maintain a high standard of quality.
+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
 
@@ -85,14 +87,14 @@ Before requesting review:
 
 ## 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
+- [ ] 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...
 
@@ -106,8 +108,7 @@ Before requesting review:
 Don’t be afraid to ask! You can:
 
 - Tag reviewers in comments
-- Use GitHub Discussions
-- Ask in Oppia’s chat or community channels
+- 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!