Node.js Node.js Interactive North America 2016, 15 Dec 2016

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: A Beginner’s Guide To Reading Node.js Core Source by Rich Trott, UC San Francisco

Description

A Beginner’s Guide To Reading Node.js Core Source - Rich Trott, UC San Francisco

An account of how one JavaScript developer (that’s me, hi!) figured out what the heck was going on in Node.js core code.

A

Okay, success, let's see so welcome to a beginner's guide to reading nodejs course source. If you came here expecting to see, oh god, she's talk. Sorry, you got me instead, see I, see some people who already know how to read node course source. So I can definitely recommend if you get bored to go to what Cadiz talk about the dark web. That should be really interesting and there's also a workshop going on right now about building apps and electrons.

A

So there's that too I'm rich trot and it's customary to talk about yourself a little bit at the start of a talk. So I work at the University of California in San, Francisco I work in the library, but I'm, not a librarian, but I am also a member of the node.js core Technical Committee. For what that's worth and no less than authority that miles Boren's has called me.

A

The hardest-working meatbag in no js' I also started something called node to do, which we will get to in a little bit but thrown that out there and I got started with node I'll. Try not to repeat too much of limb.

A

Khakis awesome 20 minutes that he gave on the stage a little while ago, but I got started with node when it was I oj s right around the time of the of the fork, and the fork was a time of some distress among in some quarters about what this meant for the future of node and the future of the platform.

A

And but there were also a bunch of people who were really excited for the reasons william described, namely that a main component of the main message of the of the iOS project was come and help us. We want your help. We need your help, there's not enough of us, and that was really exciting to me, and so why am I talking about this well we're here to talk about reading no J's core, and why would you want to do that? There's you know, there's there's a bunch of potential reasons.

A

You might want to debug a particular problem you're having with node. You might just have intellectual curiosity. How does it all work? How does it all fit together? But for me the the reason I come across the most frequently is like my cat.

A

You want to start contributing to node node, yes and so I'm kind of doing a little bit of a bait-and-switch in that I'm, hoping that this talk can encourage people to to participate in the project, contributed code or documentation or any of the number of things, because, if you're successful at that, that increases the pool of people who are participating, the project and the more you know in in theory at least the more good folks we have doing good stuff, the more the more you know, the better the project will be in the more tautologically, the more good stuff.

A

We can do so. A couple of caveats about this talk, first of all, assuming that you're coming at this from a JavaScript perspective. If C++ is your jam and you want to approach this from v8 or libuv, this talk may not be the way to do it. The other thing is what I'm describing worked for me, might not work for everybody. I, don't know just pointing that out. Step 0 write a HelloWorld program in no GS or something just get familiar with.

A

Node use it a little bit since you're at node, interactive I'm, assuming you've already done that so we're just gonna barrel through to step one.

A

Pick some documentation and read it in particular: go to the API documentation and don't try to read it. You know front to back, but pick an API. You know any API will do, but preferably one you're interested in or one you're using there's a you know if you, if you're interested in scaling, maybe check out the cluster API if you're interested if you've been writing web apps, maybe look at the HTTP or HTTPS API if you're into cryptography or something you know, look at TLS, etc, etc, etc.

A

So, there's some obvious reasons why this is a good approach and then maybe one or two less obvious reasons for one thing: if you understand how the API is used- and you know even if you've used an API a lot- you probably don't you know, there's an excellent chance. You don't know all the little bits and pieces of it.

A

If you understand how an API is used, then that provides clues to its implementation, but there's a there's, a potentially less obvious benefit to starting started with documentation and starting with a really really modular and little piece of documentation. That forces you to focus because no core is sprawling and if you decide I'm interested in X, you X can be in 18 different files, and you know it's it's good to just have one one thing: to look at just to sort of wrap your head around how something might work.

A

Additionally, if you're looking at the documentation, you might find something that's broken in the documentation, because there you know a lot of this stuff was not written by people who are professional, technical writers or anything like that. So there's going to be omissions, there's going to be errors, there's going to be all sorts of problems, and this is an opportunity for you to fix it.

A

This is this: is you know about getting an easy contribution in and improving the Docs for others, but there's also another element to going through the commit process, the code review or documentation review in this case process, and it's that there's a lot of stuff that happens during that process like this metadata gets added to commits and without getting into too much detail here.

A

I feel that it's really helpful to understand I feel that it that understanding that process is really helpful in understanding the code and how it's put together and why certain decisions were made, and if that sounds mysterious and interesting, we can talk about that more later. But I only have 20 minutes here. So there's a caveat with the whole: hey you're, reading documentation, you found something missing fix it. It's that documentation is not easy. It's a it's a real pet peeve of mine, actually that a lot of projects will take documentation.

A

In fact, I just did this this morning, but a lot of projects will take open, have open issues around documentation and, let's mark them good first contribution that meeting documentation is not hard. Writing. Good documentation is incredibly hard and documentation. Skills are a super power. If you have the superpower, please use it for good and help out, but so step. Two after you've read some documentation is to look at some code. Fortunately, our code is not minified like this.

A

This is just a metaphor or something I guess, but if you were looking, if you're reading about the cluster module going to live and look at Lib cluster j/s, if you're looking at HTTP look at Lib, HTTP is etcetera. Some of these module files are pretty short and digestible. Some of them are kind of long and you're.

A

Gonna want to just look at the the parts that are of interest to you, but look at the core source code, and one secret about node core is that these files are pretty understandable, pretty approachable the thing that usually trips people up when they first approached them, at least from you know, anecdotal experience anyway, is is, is actually misunderstanding: the API, or not understanding how modules load, but while reading these, these files, you're gonna find stuff that you may not know exists like process, not binding, which I, don't think is actually documented.

A

So when you find stuff like that, this is you know. This sort of these are the sorts of pieces that that will help. You understand how the code actually works and how it all fits together. You you can look in the documentation for things or for things that aren't in the documentation. You can go to the node dev channel on the on freenode IRC and ask their so on and so forth.

A

So step 3. After all that, because you know well, I've read the code to understand it, but I recommend finding the tests for that module and reading through the tests, because sometimes there's behavior, that's only documented in tests and that's kind of where things get really interesting.

A

So if you were looking at HTTP, you might look in tests parallel tests, HTTP whatever yes and for HTTP, there's going to be way too many test files to just sit and read through you'll you'll want to. You know, poke your eye out or something. But but you can just look at test. Sacc, pjs and sort of just get a feel for the test. Also how the tests are written is super important if you're gonna contribute, especially chances are you're going to need to write a test.

A

So there's the readme file and the test directory has some information about how tests work and are put together, but the real goldmine is probably the the writing underbar test MD file. That's in doc, slash guides, it's really short, really understandable, really well-written and it's a good good resource, so bait-and-switch we're moving right into contributions.

A

So if you have your laptop open, I think you should probably read by now might be a good time to go to node to do n OD eto do dot o-r-g and you'll, see something that looks like this and you'll see a getting started guide link and if you click on that it goes to a gist that looks like this and the first few things in it are going to be pretty straightforward.

A

There's you know, if you don't already have a github account, you should create a github account if you haven't forked repo fork, the repo, but it takes you to the steps to clone and then build and run tests and then, at the end, after you've run your tests.

A

It says why don't you send an email to us or tweet at us and we'll give you a really easy, or at least maybe not easy, but certainly manageable, and good first contribution to provide to know to improve, to improve the the codebase and sort of you know, hopefully get you hooked, and then you start finding your own issues and stuff. If this sounds an awful lot like code and learn which is happening on Thursday morning, which I recommend you come to as well.

A

That's because it's basic the same thing that wasn't on purpose code and learn was originally conceived as a way to get people interested in the darker corners of the code base that nobody understands, or only one or two people understand and we'd, have those one or two experts there and they would sort of train people and help them out and I. Don't uh I haven't been to you know. You know there was code and learned event in London and one in Amsterdam and so and so forth.

A

Yeah I haven't been to you know most of them any of them, but my impression is that it never really. Quite worked out that way and that it kind of sort of evolved into a good first contribution. The kind of experience like I just described so sort of two things that just sort of happened independently. The main difference is code and learn is you know, is affiliated with the foundation foundation and know to do is just something that me and two other people do hopefully, hopefully more by the way for those of you.

A

People who are like you know already have contributions in and want to help other people get started. I do I, could use some help, answering emails and tweets so yeah. So that's me, that's no dude! That's the URL and I thought. I was gonna, have way less time at the end and avoid the dreaded Q&A I still might do that by saying I'm not doing Q&A and I'll just be kind of like hanging out over here so yeah. That's it thanks a lot.