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
{{ message }}
Repository navigation
Design decisions for the tutorials (Please read this before suggesting changes) #35892
This is not an issue, but more of a documentation of the design choices we made for the tutorials and what we learned from community feedback.
1. Keep the tutorial short
I think this is one of the most important aspects that helped this project grow. Getting a pay-off within five minutes of learning something is remarkable. For brevity, we have to compromise on details. A lot of details are missing from the main tutorial. From explanations on what actually happens when you run those commands to other good practices one could follow.
2. Accessibility matters
We want these tutorials to be accessible to as much people as possible. Be it somebody having trouble with language barriers or someone with limited internet speed. Translations help people understand this in languages they're more comfortable with. Keeping the size of this repository small will help with limited bandwidth.
3. Contributors.md doesn't matter
This is one point where I had multiple discussions with the community. Contributors list exists just as a file you can edit to work through the tutorial. How it looks or what you add there doesn't matter. We'll remove most entries in it from time to time because we don't want someone being left out because their text editor can't open a huge file.
4. Be generic.
We could make assumptions about what OS most of our users are using or what terminal emulator or text editor they're comfortable with. By not making such assumptions, we give our readers more freedom and include more people.
Feel free to challenge any of the above in the comments. I'd love to get feedback from you. Let's have a discussion.
Also, there are things I'm struggling to design. Like how to give directions to proceed right after one finishes the tutorial. So, comment down below what you're looking for right after you finish the tutorial and what you're missing.
Reacted by Raheem Amer, Kaushal Kumar, Tushar Gupta, Naveenkumar J, Godstime Nwabue, Bladimir, Faisal Sayed , Anh Duong, philliprossii7, Silencio and 4 more
Reacted by mariaclaracorecha, Caleb Wodi and Jeremiah Isaacson
Reacted by Godstime Nwabue, saroj_r and William Alvarez
Okay yeah, Contributions.md doesn't matter, but what if we could just make it look more beautiful, allow users to add their profile pics and make it more lively :)
Hi! I'm currently working through the tutorial as my introduction to open source, and I wanted to share some feedback from a beginner's perspective.
I really appreciated how short and approachable the tutorial is. Being able to make my first contribution in a short amount of time made the process much less intimidating.
One thing I think could help after completing the tutorial is providing a small "What's next?" section that recommends a few beginner-friendly open-source repositories (organized by language like Python, Java, JavaScript, etc.) along with advice on how to find a good first issue. That would make it easier for new contributors to transition from the tutorial to real-world projects.
Hi! I just completed the tutorial and had my PR merged. I’m a data science and psychology student and this was my first open source contribution.
What worked: the steps were short and easy to follow, and I got through fork, clone, branch and PR without trouble.
Where I got stuck: my PR showed “Can’t automatically merge” because many people add their name at the end of Contributors.md at the same time. I didn’t know this was normal. Some lines in that file also contain leftover conflict markers (<<<<<<< HEAD), so GitHub’s conflict editor looked confusing. I ended up syncing with upstream, resetting my branch, re-adding my line and force-pushing, which I only managed with outside help. I also got “Auto-merge PRs workflow failed” notifications and wasn’t sure whether I’d done something wrong.
Suggestions: (1) add a short note saying conflicts at the end of the file are common and what to do, with a link to the conflict guide; (2) add a “What’s next” section. I agree with the earlier suggestion, and for people from data science or research backgrounds it would help to include a short list of beginner-friendly Python and science repos and how to find “good first issue” labels.
Thanks for maintaining this, it was a really great starting point for me.
Activity
sambhavsaxena commentedon May 11, 2021
peterthankgod commentedon Apr 3, 2022
johan237 commentedon Apr 21, 2022
sambhavsaxena commentedon Apr 22, 2022
pichpeyman commentedon Sep 29, 2022
Mihails79 commentedon Aug 9, 2023
None
remove lines from contributors.md
asterdoescomputing commentedon May 15, 2026
Okay yeah, Contributions.md doesn't matter, but what if we could just make it look more beautiful, allow users to add their profile pics and make it more lively :)
Pallavi-vi-1234 commentedon May 26, 2026
Hi @maintainer,
I would like to work on this issue under NSoC 2026.
Can you please assign it to me?
Thank you!
SRamkumar190 commentedon Jul 18, 2026
Hi! I'm currently working through the tutorial as my introduction to open source, and I wanted to share some feedback from a beginner's perspective.
I really appreciated how short and approachable the tutorial is. Being able to make my first contribution in a short amount of time made the process much less intimidating.
One thing I think could help after completing the tutorial is providing a small "What's next?" section that recommends a few beginner-friendly open-source repositories (organized by language like Python, Java, JavaScript, etc.) along with advice on how to find a good first issue. That would make it easier for new contributors to transition from the tutorial to real-world projects.
Thanks for maintaining such a great resource!
Roshanjossey commentedon Jul 19, 2026
Hi @SRamkumar190, could you describe your user experience after you finished the tutorial?
kyraa-up commentedon Nov 20, 2026
Hi! I just completed the tutorial and had my PR merged. I’m a data science and psychology student and this was my first open source contribution.
What worked: the steps were short and easy to follow, and I got through fork, clone, branch and PR without trouble.
Where I got stuck: my PR showed “Can’t automatically merge” because many people add their name at the end of Contributors.md at the same time. I didn’t know this was normal. Some lines in that file also contain leftover conflict markers (<<<<<<< HEAD), so GitHub’s conflict editor looked confusing. I ended up syncing with upstream, resetting my branch, re-adding my line and force-pushing, which I only managed with outside help. I also got “Auto-merge PRs workflow failed” notifications and wasn’t sure whether I’d done something wrong.
Suggestions: (1) add a short note saying conflicts at the end of the file are common and what to do, with a link to the conflict guide; (2) add a “What’s next” section. I agree with the earlier suggestion, and for people from data science or research backgrounds it would help to include a short list of beginner-friendly Python and science repos and how to find “good first issue” labels.
Thanks for maintaining this, it was a really great starting point for me.