New Contributor Tutorials

For a little while I have been contemplating how new contributors could be most helpful to the community in regard to where we have the most need. My current perspective is that we likely do not need many more folk doing actual code contribution, but do need folk to review existing PRs that are in the queue, or helping with other repos in the Django organisation.

As such I wondered if there would be a benefit to creating some new contributing tutorials around the specific needs we have. First up to my mind would be walking folks through how best to do a code review for Django.

The goal to me here is also to highlight that there is no gatekeeping on who is allowed or not allowed to review code. This myth or old way of thinking still exists to those new to Django and those I know that have worked with Django for most of its existence while not being so active in the community.

This also aligns to my mind to the changes in recent years of broadening the recognition to being considered for community roles.

Finally I did create a ticket along these lines, but as Sarah suggested a forum discussion would be beneficial: #37460 (Create a second new contributors tutorial which teaches Code/PR Review as a valid contribution path) – Django

5 Likes

To me, a tutorial is a specific set of steps that we guide a person through and they actually perform these steps to get a “feel” of doing the work.

We could have a patch file for folks to review, but for this to be good, we need to keep this patch file up-to-date so it applies cleanly on main.

We do not want someone doing a tutorial to cause “noise” to the project (such as creating “toast” PRs or example adding comments on a real PR).

I am happy to have a more in-depth “Review” topic which covers many things, but I don’t currently see how a tutorial could be put together and work for the project.

1 Like

One option to make this technically feasible is to have a github template repo that could be copied, with a command to generate the PR for the user within that cloned repo.

My view on a ‘tutorial’ here is perhaps a wider definition than the one in the docs definition. It may not be a specific set of steps for someone to do, but perhaps reading past examples of a good reviews and not great reviews with the context of what made them good/bad.

Whether this document turns out not the be a specific tutorial or a review topic to me is at this point beside the point. To me it’s the positioning of said document to be next to the existing new contributor tutorial. The goal in my mind is that when new contributors come to the website/forum or Discord they have a choice as to what contribution path they would like to take and we as a community can then nudge folks one way or the other depending on the current need.

I don’t think there’d be opposition to creating the content. Perhaps on how to keep it fresh though. It does appear there’s confusion around where this goes and how it will work though. Both Sarah and I got caught up on the word tutorial which our understanding doesn’t seem to match yours.

It may be better for you to create a first draft of the material and we curate it from there. Worst case, it ends up as a blog post on djangoproject.com. Which is still a really nice win since search will include it.

2 Likes

…“Adds to the todo list” :sweat_smile:

That’s fair and also the idea is still evolving in my head, hence the open conversation here & the ticket, but I’ll get something written as a starter!

3 Likes

Could refactoring Advice for new contributors first be helpful? If one of the main drivers is to convince new people there is a bottom step they can reach, spell it out in big text at the top of the page. Perhaps make it a bit fun and colourful to help allay the idea you’ll get smacked on the wrist.

We need you. Yes, you!

If you’re wondering whether you’re ready to contribute to Django, the answer is almost certainly yes!

And suggest a typical progression depending on what seems most natural or likely to get people to hang around. Help with documentation → triage a ticket → enhance the website → update an old patch → review someone else’s PR → submit your own PR → work on a DEP.

Or a semi-ordered list of tiles like on Django Community | Django

Each of those avenues to help becomes its own page with links to howtos that explain the skills required to contribute in that way. The “contributing code” tutorial becomes one of several, alongside Andy’s new suggestions.

Want to write documentation? You need to be able to: 1. understand Django’s voice, 2. create a fork and check it out, 3. build the docs locally, 4. lint your changes. Review someone’s PR? You need to be able to: 1. learn about the problem space, 2. assess thoughtfully, 3. check out someone else’s fork, 4. install Django locally, 5. run tests, 6. run prek, 7. leave good PR feedback, 8. update Trac. These could be chunked in ways they can be reused across multiple contribution tracks.

We end up with a number of skill building blocks (including soft skills) that people can dip into over time and improve their confidence. All while undermining that old assumption you need to know how to do everything before you can do anything.

3 Likes

I like the breakdowns you’re sharing. Djangonaut Space has a page of contributing opportunities which sounds a bit like what you’re after: https://djangonaut.space/contribute/opportunities/