personal experiences contributing to large open source projects

[ashleygwilliams]

been seeing some tweets about how currently open issues as well as generally contributing to Node.js are intimidating and "scary".

for example:

• https://twitter.com/_lrlna/status/688136193846845442
• https://twitter.com/Charlotteis/status/688132248487395328

feedback requested:

• experiences of Node.js being "scary" + why
• experiences of other large OS projects being "scary" + why
• experiences of large OS projects not being "scary" + why

comments that do not fit into requested feedback will be removed. thanks!

[kosamari]

experiences of Node.js being "scary" + why

There is no documentation on how repo is structured. Even if I find issue I might be able to contribute, don't know where to look for files.

experiences of large OS projects not being "scary" + why

Honestly after seeing this talk by @Fishrock123 (especially from 11:15 ~) things are alot less scary.

[varjmes]

experiences of large OS projects not being "scary" + why

Lots of voices means that someone will always disagree with you (not a bad thing), and may not do it with tact (something I am currently dealing with elsewhere). No sense of direction or where to start getting involved (if I hadn't been notified of this Repo I'd still be lost).

Though am about to watch @Fishrock123's talk so maybe that will help :)

experiences of Node.js being "scary" + why

seconding @kosamari's point. a lot of people get involved by building tools or fixing bugs they notice but what if you just want to join in for the sake of it? Particularly a salient point for beginners like myself who started learning Node yesterday :)

experiences of large OS projects not being "scary" + why

Not large, but touching upon the work I do with Hoodie (which may not scale to an org of Node.js Core size but maybe for Inclusivity). Friendly atmosphere, good tweets and reachout by members of the community, blog posts updating on direction of the project and status, and editorial team who makes sure the right language is being used and a public Slack channel we openly encourage people to join even if they just want a friendly chat.

---

A note on the Inclusivity WG being a little scary: I've read all the Issues in this repo and there seems to be a real threat of any member of the WG being trolled/harassed. Not the fault of the WG, but something that certainly makes this not without fear. Also in terms of "confusing", there are a lot of dropped conversations that are still open issues and I don't know if it's because we forgot to close them, or because we still need to discuss them.

_lrlna made a great note of having a 'Getting Started' repo or guide for Node.js which I'd love to see happen / help with if thats a thing we think is achievable.

[mikeal]

There is no documentation on how repo is structured. Even if I find issue I might be able to contribute, don't know where to look for files.

This assumes you found the right repo. We don't have a documented taxonomy of the repos and working groups and what they are used for either which makes this even worse :(

[Fishrock123]

I think my Node.js Interactive talk is relevant here since it also touches on these things: https://youtu.be/9tbKIRbuF6k

experiences of Node.js being "scary" + why

Node.js is non-trivially complex, and pretty large parts are very much code spaghetti. If you clone the repo and take a look at the files, you probably won't know where the running code for a specific thing is, and if you do open a file, chances are it will be difficult to understand or won't be what you are looking for.

The whole C++ and JavaScript thing doesn't really help this much.

That basically sums up my starting experience. I worked on the website and issues until I started to slowly understand where and what everything was.

[Trott]

experiences of Node.js being "scary" + why

At least once Node Forward/io.js were happening, it mostly wasn't scary for me. I'm bringing this up not to say that Node.js isn't or can't be scary, but rather to highlight the point that just because something is welcoming and non-scary to a large set of people doesn't mean that it isn't simultaneously non-welcoming and scary to a different large set of people. Those of us who don't or haven't found Node.js to be an intimidating place should bear that in mind, no matter how many examples of like-minded people we can point to.

experiences of other large OS projects being "scary" + why

(EDIT: Whoops, this isn't really "large" I guess.) I submitted a PR to an open source project maintained by a Very Well-Known Open Source Developer with a reputation for generosity, helpfulness, kindness, all that good stuff. Alas, my contribution had whitespace thrashing due to my editor settings. They reprimanded me in the GitHub PR and then tweeted about it to all their followers using profanity and providing a link to the diff which had my name right at the top. In retrospect, nobody remembers this stuff for more than ten minutes (especially if you're a white male). But at the time, I felt completely humiliated. I wanted to crawl under a rock and never contribute in the open again.

experiences of large OS projects not being "scary" + why

For me, io.js was not scary. The messaging was welcoming, and individuals involved in the project seemed to take an interest in me and guaranteeing my success and not just taking an interest in the particular PR or other contribution I was making and guaranteeing its success. Basically, feeling like I had multiple mentors was immensely helpful.

[ashleygwilliams]

@benjamingr @Qard this issue is for relaying experiences only. if you want to discuss solutions, please do so on the Program Issue here: #96

thanks!

[ashleygwilliams]

@Qard: moved your comment here: #96 (comment)
@benjamingr: moved your comment here: #96 (comment)

[domenic]

experiences of large OS projects not being "scary" + why

Really not sure if this belongs here or in #96, so please feel free to move if it's the wrong place.

In the WHATWG organization, especially the whatwg/html repo, we've had moderate success de-scaryifying our large (6 MB) spec via the "good first bug" label. We actively curate these good first bugs, with the editors of each spec purposefully not fixing them for some time, leaving them for community members who want to get started contributing.

We also quickly realized that a key ingredient in a "good first bug" in this sense is clear direction on what the fix needs to be, even to the point of being over-explicit. For example, in whatwg/html#615 and whatwg/console#39 I specifically spelled out the exact textual changes I would suggest, which the authors of the resulting PR took as the basis for their work. That leaves contributors to focus on the mechanics of pulling down and building the spec, and submitting a good PR, instead of figuring out exactly what the bug is and how to fix it, which can sometimes involve reading long issue threads where the exact problem and solution change over the course of the discussion.

(Note: if I were to apply "good first bug" to Node.js, I'd have "good first c++ bug" and "good first js bug".)

Finally, we tried to make it relatively easy process-wise to get started on fixing these good-first-bugs. We kept the README short and focused almost entirely on how to contribute: https://github.com/whatwg/html#pull-requests and even though we have an arcane build process (whatwg/html-build), we spent a lot of effort iterating on making it as easy as possible, e.g. making the build.sh script interactively guide you through forking and cloning the source repo, and aggressively eliminating build-system dependencies so people could contribute without installing a bunch of prerequisite software. We're even working on creating a Docker image for the build environment, which for those people who are familiar with Docker will eliminate all dependencies except Docker.