Opened 3 weeks ago

Closed 3 weeks ago

Last modified 13 days ago

#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 Sarah Boyce, 3 weeks ago

Cc: Tim Schilling added
Resolution: → needsnewfeatureprocess
Status: new → closed

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

Last edited 3 weeks ago by Sarah Boyce (previous) (diff)

comment:2 by Tim Schilling, 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 site. Aligning it into a structured tutorial would be helpful. The patch review checklist is 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.

Last edited 3 weeks ago by Tim Schilling (previous) (diff)
Note: See TracTickets for help on using tickets.
Back to Top