You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: getting-started/pull-request-lifecycle.rst
+44-44Lines changed: 44 additions & 44 deletions
Original file line number
Diff line number
Diff line change
@@ -190,81 +190,81 @@ Making Good PRs
190
190
191
191
When creating a pull request, following best practices ensures your contribution is **clear, maintainable, and easy to review**. A well-structured PR improves collaboration and speeds up the review process.
192
192
193
-
1. **Use a Clear and Structured PR Title**
193
+
1. **Use a Clear and Structured PR Title**
194
194
195
195
PR titles often become commit messages, making them **critical for maintainability and searchability**. Follow these guidelines:
196
196
197
-
**Do:**
198
-
199
-
- Clearly summarize the change in a concise manner.
200
-
- Use the **imperative mood** (e.g., "Fix crash in parser" instead of "Fixed a crash in parser").
201
-
- Be specific about what is being changed (avoid vague words like "Update" or "Fix").
197
+
**Do:**
202
198
203
-
**Avoid:**
199
+
- Clearly summarize the change in a concise manner.
200
+
- Use the **imperative mood** (e.g., "Fix crash in parser" instead of "Fixed a crash in parser").
201
+
- Be specific about what is being changed (avoid vague words like "Update" or "Fix").
204
202
205
-
- "Bug fix" → Too vague. What bug was fixed?
206
-
- "Update README" → What was updated? Be precise.
207
-
- "Refactoring" → Explain what was refactored and why.
203
+
**Avoid:**
208
204
209
-
**Example of a good PR title:**
205
+
- "Bug fix" → Too vague. What bug was fixed?
206
+
- "Update README" → What was updated? Be precise.
207
+
- "Refactoring" → Explain what was refactored and why.
208
+
209
+
**Example of a good PR title:**
210
210
211
211
``Improve error handling in JSON parser to prevent crashes``
212
212
213
-
2. **Write a Meaningful PR Description**
213
+
2. **Write a Meaningful PR Description**
214
214
215
-
Your PR description should provide **clear context** for reviewers. Answer the following questions:
215
+
Your PR description should provide **clear context** for reviewers. Answer the following questions:
216
216
217
-
- **What does this PR do?**
218
-
- **Why is this change necessary?**
219
-
- **Are there any breaking changes?**
220
-
- **Does this PR fix any open issues?** (Reference issue numbers if applicable)
217
+
- **What does this PR do?**
218
+
- **Why is this change necessary?**
219
+
- **Are there any breaking changes?**
220
+
- **Does this PR fix any open issues?** (Reference issue numbers if applicable)
221
221
222
222
Providing detailed descriptions makes the review process **faster and more efficient**.
223
223
224
-
3. **Make Your Change Against the Right Branch**
224
+
3. **Make Your Change Against the Right Branch**
225
225
226
-
Ensure your PR is based on the correct branch:
226
+
Ensure your PR is based on the correct branch:
227
227
228
-
- **New changes should target the** ``main`` **branch unless they are specific to an older version.**
229
-
- If a change affects older versions, it will be **backported** after merging.
230
-
- Only use **maintenance branches** when the change does not apply to ``main`` or requires a different approach.
228
+
- **New changes should target the** ``main`` **branch unless they are specific to an older version.**
229
+
- If a change affects older versions, it will be **backported** after merging.
230
+
- Only use **maintenance branches** when the change does not apply to ``main`` or requires a different approach.
231
231
232
232
Refer to :ref:`branch-merge` for more details on how backporting works.
233
233
234
-
4. **Follow Python's Style Guidelines**
234
+
4. **Follow Python's Style Guidelines**
235
235
236
-
- Python code should follow :PEP:`8`, and C code should follow :PEP:`7`.
237
-
- Maintainers may **fix minor style issues**, but major deviations can **delay or block merging**.
238
-
- PRs with **only style changes** are usually rejected unless they fix a formatting error.
236
+
- Python code should follow :PEP:`8`, and C code should follow :PEP:`7`.
237
+
- Maintainers may **fix minor style issues**, but major deviations can **delay or block merging**.
238
+
- PRs with **only style changes** are usually rejected unless they fix a formatting error.
239
239
240
-
.. note::
241
-
Fixes for typos and grammar errors in documentation and docstrings are always welcome.
240
+
.. note::
241
+
Fixes for typos and grammar errors in documentation and docstrings are always welcome.
242
242
243
-
5. **Consider Backward Compatibility**
243
+
5. **Consider Backward Compatibility**
244
244
245
-
- Changes should **not break existing code** unless absolutely necessary.
246
-
- When introducing **new arguments**, provide **default values** to maintain existing behavior.
247
-
- If unsure, refer to :PEP:`387` or discuss the issue with experienced maintainers in :ref:`communication`.
245
+
- Changes should **not break existing code** unless absolutely necessary.
246
+
- When introducing **new arguments**, provide **default values** to maintain existing behavior.
247
+
- If unsure, refer to :PEP:`387` or discuss the issue with experienced maintainers in :ref:`communication`.
248
248
249
249
Think about how your change affects existing users before submitting your PR.
250
250
251
-
6. **Ensure Proper Testing**
251
+
6. **Ensure Proper Testing**
252
252
253
-
- Every PR should include **appropriate test cases** to validate the changes.
254
-
- PRs without tests **will not be accepted** unless they are purely documentation changes.
255
-
- Tests should **cover edge cases** and expected behaviors.
256
-
- For bug fixes, add a test that **fails without the fix** and **passes after applying it**.
253
+
- Every PR should include **appropriate test cases** to validate the changes.
254
+
- PRs without tests **will not be accepted** unless they are purely documentation changes.
255
+
- Tests should **cover edge cases** and expected behaviors.
256
+
- For bug fixes, add a test that **fails without the fix** and **passes after applying it**.
257
257
258
-
7. **Make Sure All Tests Pass**
258
+
7. **Make Sure All Tests Pass**
259
259
260
-
- The entire test suite must **run without failures** before submission.
261
-
- Run ``make test`` or refer to :ref:`runtests` to check for test failures.
262
-
- Do not submit PRs with failing tests unless the failure is **directly related** to your change.
260
+
- The entire test suite must **run without failures** before submission.
261
+
- Run ``make test`` or refer to :ref:`runtests` to check for test failures.
262
+
- Do not submit PRs with failing tests unless the failure is **directly related** to your change.
263
263
264
-
8. **Keep Documentation Up to Date**
264
+
8. **Keep Documentation Up to Date**
265
265
266
-
- Any change affecting functionality should include relevant **documentation updates**.
267
-
- Follow :ref:`documenting` guidelines to ensure consistency in documentation.
266
+
- Any change affecting functionality should include relevant **documentation updates**.
267
+
- Follow :ref:`documenting` guidelines to ensure consistency in documentation.
268
268
269
269
Keeping documentation updated ensures clarity for future contributors and users.
0 commit comments