MarsBarLee commented 1 week ago

Did you enjoy the NumPy comics from my Lightning Talk? Have a bold new vision or idea of the next edition? Let me know, let's sprint on it!

Some ideas

Making your first pull request + how to understand a codebase
Making full use of community calls, slack, Mailing list (especially in making a pull request)
preventing and dealing with contributor burnout
informative vs narrative comics

After the sprint: I'm looking into applying for the Google Season of Docs 2025 with NumPy with our sprint idea

MarsBarLee commented 1 week ago

PXL_20240907_193158924 MP Notes from my sprint session with Ross.

MarsBarLee commented 1 week ago

Next Comic: Making your first PR in NumPy

Logical starting point: Making a sequel to the first comic, using the same characters

Ties to the topic 'Understanding the Codebase' and 'Making full use of the Community Call, Slack, Mailing list'

Understanding the Codebase

There are some existing guides to understanding a big codebase eg this guide.
My goal would be to take this general advice and make specific to NumPy and open source.
The strength of making resource specific to NumPy: NumPy is a foundational package made nearly 2 decades ago- it's very worthwhile to contribute but since the codebase is so big, it can be intimidating and hard to start
The comic would got through a specific part of the codebase eg .npz filetype change in more detail ie a case study
Ross will ask NumPy team if there's any IRL examples eg past PRs we can use for the story

Showing the communication channels the NumPy community uses would highlight the parts that makes open source unique. How the process may differ from propriety software and internal teams eg what is etiquette on volunteer basis
Can close the gap, intimidation of now know who the NumPy community is, how they will respond to your issue
How Community Call is great human starting point
'the value of a triage call to focus specifically discussing the implementation of a PR,
how communication can move over to Slack
the value of the mailing list for broadly reaching entire NumPy community
The subtitles of what communication channel is good for what may not be obvious to those outside of NumPy

Student A is using NumPy for their cell imaging research
However, they face Problem X and want to write their own solution
They eagerly start looking into the NumPy codebase, but get intimidated by the large codebase
Eventually they find a part that matches, maybe they could change
However, they're not entirely sure
They remember that the NumPy team meets at the Community Call- that could a good starting point
Student A goes to a NumPy Community Call to ask 'I want to solve Problem X by making Solution Y. Is this a step in the right direction?'
NumPy team member, Contributer B provides guidance, big picture overview, and possible
Student A feels affirmed of moving in right direction, got some correction and most of all, a human connection
Contributor B says 'Let's continue this conversation on Slack, I'll walk you through it in more detail"
Student A and Contribute B talk on Slack, and then decide to meet at Triage call
Student A and Contributor B get in Triage call to go through codebase,
Student A works on Solution Y
Student A submits their first PR, with context of both the full NumPy codebase and guidance of NumPy team
Student A's PR is reviewed by Contributor B and a NumPy maintainer
Student A PR is merged! Problem X has been solved with Solution Y!
Solution Y is announced on the mailing list

Scope problem

Possible Solution

Split up the grant and this story over 2 separate grants and 2 separate comics over 2 years
Other discussion points

Changing NumPy on the C level

Some of the biggest, worthwhile changes are at a C level
However, the C level is more complicated, and not a common starting point for a newcomer such as Student A in the comic
Maybe a future comic could talk about NumPy at a C level

Promote best practice: test-driven development

Ross mentioned the importance of test-driven development- a comic could talk about why that's a worthwhile best practice and why do that in NumPy
Test behavior and constraints by implementation
See what you want it to do and not to do, experience in CI, trial and error with helpful errors you can build off of
Learn with confidence - see Red X into Green ✓
Method: How do I teach myself?

Selecting a good first PR: Reality vs Story

Docstring changes are approachable contribution a newcomer could make, but is often isolated from the rest of the codebase and may be bikeshedded.
For a story that teaches how NumPy codebase works, more worthwhile to tackle changing the codebase, even if that's more difficult to do

MarsBarLee commented 1 week ago

Next steps after this Summit Sprint:

I'll bring this conversation to the next NumPy Community Call
Decide on story scope
Ask NumPy team about if there's a previous example/real PR that we could use for the story.
Write grant application for GSOD 2025