#37460 closed New feature (needsnewfeatureprocess)
Create a second new contributors tutorial which teaches Code/PR Review as a valid contribution path
| Reported by: | Andy Miller | Owned by: | |
|---|---|---|---|
| Component: | Documentation | Version: | 6.1 |
| Severity: | Normal | Keywords: | |
| Cc: | Tim Schilling | Triage Stage: | Unreviewed |
| Has patch: | no | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | no | UI/UX: | no |
Description
Most new contributors seem unaware that they are qualified to do code reviews for existing open contributions to Django.
This ticket proposes the creation of a second tutorial to teach what we expect as a community from a new contributor doing a code review.
The benefit here is the provide an on-ramp to the code review process, with the broad goal to increase the number of potential reviewers and to elevate the status of the stage in the overall contribution process. As I understand it, the code review step is also our current bottleneck so ought to help with this stage (or at least that's the theory)
I think this page would also benefit from providing some illustrations of good and bad reviews from the past (these could be anonymised for those involved)
Change History (3)
comment:1 by , 3 weeks ago
| Cc: | added |
|---|---|
| Resolution: | → needsnewfeatureprocess |
| Status: | new → closed |
comment:2 by , 3 weeks ago
I feel like a tutorial implies that it's a step-by-step process similar to the contribution tutorial. I think we could use one of those for the code review flow. I think the documentation has bits and pieces spread across the documentation, but aligning it into a structured tutorial would be helpful. The patch review checklist are written as a how to guide, which is a great start, but for someone not knowing how to exactly install Django from their local version into a separate project, it falls short.
The bit about clarity of scope, having Andy outline what the steps are could align us on that fairly quickly.
comment:3 by , 13 days ago
I created a forum topic: https://forum.djangoproject.com/t/new-contributor-tutorials/46359
Hi Andy, thank you for the ticket!
I am not sure I agree with adding a new tutorial here, so I am marking this as "needsnewfeatureprocess" for now.
I think a discussion is needed to define the scope and what is needed here. A forum post is sufficient though rather than the new features board
Are you aware that there was recently guidance added on reviewing patches? See https://docs.djangoproject.com/en/6.1/internals/contributing/triaging-tickets/#reviewing-patches
We also have advice for new contributors to review patches, see https://docs.djangoproject.com/en/6.1/internals/contributing/new-contributors/#review-patches-of-accepted-tickets
But I always think we can make improvements!
Currently, this guidance is within “Triaging tickets. We could move this to a separate page, since reviewing patches is a different activity from ticket triage. This would also give us room to expand the guidance, including a “Who can review?” section. See NumPy’s reviewer guidelines here: https://numpy.org/doc/stable/dev/reviewer_guidelines.html#who-can-be-a-reviewer
I think the review patches advice for new contributors should link to this page (or at least the current section we have).
That page perhaps could add some review examples you were thinking
I also noticed that "Triaging tickets" is the very last item of the contributing index (see https://docs.djangoproject.com/en/6.1/internals/contributing/)
The review section is the last section of the last item, so if someone was "browsing" the contributing docs, the review section is currently "dead last". (Not a huge problem, something has to be last). We could have a rethink about the index page and what is a good order of things