Getting Started in Node.js Internals Program

[ashleygwilliams]

per responses in #86

[ashleygwilliams]

from @Qard

Docs WG member here. 👋

We've planned on documenting node internals structure better. I started work on it awhile back with a quick summary of the internals, but we definitely need more useful content in that regard. As someone that already lives deep in the codebase, I could use someone less familiar with it to pair with for perspective. If anyone would like to share their views on what docs could do better here, I'd be super grateful. 😸

@nodejs/documentation Anyone else from docs able to get involved in improving internals and onboarding type docs?

[ashleygwilliams]

from @benjamingr

I gave a talk about open source contribution and Node in a conference last year and I did some polling before that. Mostly - people were afraid that they don't know the code structure and how it works and were under the impression only code consists of a contribution.

I think something that could help is pairing people who want to help with people who have more repo experience so people who want to help are given some basic guidance beyond responses on the PR. Not sure how practical that is though.

[eljefedelrodeodeljefe]

I was starting writing a blog post for "Writing a whole stack feature for Node.js" with the first sentence "DO NOT do this ever, but try here...", basically doing something on the JS side down via v8 to libuv and having it checked in into the various build tools... stuff like this? The only part I am missing though was how JS strings get evaluated by the VM and eventually call C/C++ deps.

[techjeffharris]

@Quard, I have been trying to follow the project since the inception of io.js but I don't yet feel entirely comfortable writing PRs or bugfixes beyond just documentation as there are a lot of things that affect other things and I worry I'll unknowingly screw something up >_<

That being said, I would love to work with someone who is more familiar, comfortable, and would be willing to provide some guidance and answer questions to help improve the state of the docs which would only help myself and others get a better understanding of how Node.js works under the hood and therefore how to contribute.

[a0viedo]

@ashleygwilliams is this a "Getting started in Node.js" (applications) or "Getting started in Node.js" (internals)?

[varjmes]

@a0viedo I believe it is internals :)

[techjeffharris]

@ashleygwilliams sorry I didn't also mention you! I am one of those that is generally familiar with the project, but not so much the codebase and would love to provide some insights of my perspective.

[Fishrock123]

A bunch of prior work listed here: nodejs/node#4931 (comment)

[williamkapke]

https://github.com/nodejs/code-and-learn
Related?

[ghost]

after today's meeting, in which this was discussed, i'd like to update this a little bit.

we've been discussing on how to take this further. perhaps through a WG or another manifested group. i'd like to get some people that are interested in this topic and discuss where we can take this.

/cc @Charlotteis @scottgonzalez @nodejs/documentation @nodejs/evangelism

[benjamingr]

I actually have a few people who I've helped get into Node - I try to do it.

It is easy to divide into two subgroups:

• people who got into it got into it fast and hard (and some have since become core collaborators).
• people who stared at "good first contribution" for an hour and then got stuck, asked for assistance, got stuck again, asked again and eventually gave up.

Honestly, people of the first type are usually much more helpful to the project - I think it would be great if we could get more of them and place focus there.

I have experimented with helping people "get into Node", I speak at meetups pretty (but not very) frequently here (about once a month) - I typically end with "Hey, if anyone wants to get involved in Node - the project is looking for collaborators. Feel free to personally contact me and I will help you get involved". People actually do approach me afterwards so it does make it seem a lot more approachable but a lot give up before making the real first contribution. Typically the first commit is the largest barrier.

[williamkapke]

I want resurface what @a0viedo mentioned:

is this a "Getting started in Node.js" (applications) or "Getting started in Node.js" (internals)

... and then there are people that want to get involved with the community or evangelism (non code writing)

Can we rename this to be explicitly "Node.js Internals"? It keeps throwing me off.

[julianduque]

@williamkapke renamed the issue to avoid confusion

[Fishrock123]

This sort of thing keeps on coming back around to me. I still find it consistently difficult to find good issues for newcomers to work on.

Node core isn't super friendly for contributions with little time backing them. Core is often pretty hard (even for me) but that can be OK so long as you're willing to dedicate some time. If you don't have any time, it's just going to be rough.

[Fishrock123]

And by hard I mean the actual technical details of a cross-platform software platform of this size are usually non-trivial.

[ghost]

i think @williamkapke makes a good point. not all potential contributors want to work on node core. maybe we should work on creating some kind of guide that includes all possible ways to contribute to node or something?

what i think would be a good starting point would be to form a separate team/group to work on this general topic. maybe with members from here, the TSC, the docs wg and the evangelism wg (ideally)?

[jcrben]

Maybe some good external resources somewhere can serve as a foundation? I'd prefer an intro with plenty of source code or at least symbol references, altho I realize it's tough to keep it maintained in a fast-moving codebase. There's lots of articles out there that discuss the event queue at a high-level tho which doesn't really help. Also, maybe point to general advice on how to approach a large codebase - I personally find it helpful to step through the code for some of the major control flows.

Architecture of Node.js’ Internal Codebase (2016) is decent altho still a bit high-level. Of the official guides, https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/ is a bit more more internalish. There's also https://github.com/nodejs/code-and-learn but it's just a list of people.

I sometimes peruse the literature around internals for languages and nodejs seems weaker than others which isn't surprising given its youth. Python doesn't do a good job officially, but there's plenty of good stuff out there, including 10 hours of lectures on Python internals. PHP is similar.

Maybe not totally fair to compare those runtimes to something like nodejs, altho more broadly the literature around V8 internals seems limited as well .