Skip to content

Contributing To Node.js Docs the Hard Way

Posted on:March 23, 2023

I’m not exactly a mega-genius when it comes to grammar, speling, punctuation, stuff, like, that; 🤪 but sometimes, obvious spelling mistakes, broken links and misplaced apostrophes kinda bug me. They bug me to the point where I’ll try and fix it if I can. And I like doing it.

I wish I could say that I’ve contributed actual code to open source projects, but my history with contributing to various projects is entirely typos and broken links. I think my first contribution was to the excellent SilverBullet here, where I found a typo while reading the docs so I corrected the mistake and sent in a pull request. I was thrilled when it got accepted and merged.

Another one of my first contributions was to an awesome project by Kent C. Dodds called First Contributions, whose purpose is so beginners can learn the Git and GitHub work flow. Except my perfectionism (or maybe it’s OCD) sort of got in the way with that. I had corrected the Markdown formatting of some other people’s names when all I was supposed to do was enter my own name in the file and then open a pull request. I made a bunch of fixes, like kind of a lot, and the automated tool or whatever (I’m assuming) thought that I was up to no good when it saw I had done more than that. I don’t know. But my contribution was rejected 😢.

And the swell folks at Zero To Mastery have a GitHub repo called start-here-guidelines that’s similar to First Contributions in that it exists so that learners can practice making contributions. So, I’m proud to say that I’m one of over 12,000 contributors there lol.

It’s awesome that places like these exist, because if it wasn’t for experiences like those, I don’t know that I would know how to contribute. Plus there’s always more to learn.

I don’t wanna sound like a brag but I’m proud that I’ve made quite a few of these little contributions: just yesterday I did this one, I did one for the MDN Web Docs site, here, the Bun documentation, Astro docs, Bridgetown, and more. So, I’m kind of a big deal. Lol, I’m kidding, but like I said, I enjoy helping out in my own small way.

But so on with my story concerning Node…

Here’s the original PR

While reading Don’t Block the Event Loop (or the Worker Pool) in the Node.js docs, I noticed a couple of broken links about halfway down the page.

So I forked the repo to the website, created a new branch, updated the broken links and then opened a pull request. But then there was a hiccup.🙁 My commit wasn’t signed, it wasn’t verified. I didn’t even know that was a thing.

Node.js, (and most large projects, I’m assuming) require commits to be cryptographically signed, to be “verified”. They want proof that the commit is coming from who it says it’s coming from. And GitHub shows a little badge pointing this out when “vigilant mode” is enabled.

I was already using an SSH key to authenticate with GitHub, but I wasn’t using that key, or any key, as a signing key, in order to sign my commits for them to be verified.

So how can anyone be 100% sure that the commit they’re merging is from who it says it’s from? I mean it’s easy to change your git config and have any old name and email in there, right?

Like this guy that got Linus Torvalds as a contributor to his project (spoiler, it’s fake).

Have you seen the little verified badge? It looks like this:

verified commit on GitHub

Those are commits I made for a typo fix for the Uncurled book. (That’s a good read by the way, it’s by the guy that made curl, Daniel Stenberg.) There are two commits there with an “unverified” badge (you might have to zoom in) and the middle one is the blue “verified” badge. As you can see, I wasn’t quite there yet.

There’s plenty of documentation online about how to set up your signing key, so I won’t go into that here. If you want to look into it, Atlassian has some good info on Git and SSH, here’s the GitHub docs on commit signatures, and here’s a bunch of links from Git’s own site.

What I had failed to do, was enable Git to sign off on my previous commits. The friendly gentleman, one of the Node contributors, pointed me here, to this StackOverflow thread, for information on how to configure Git to sign off on my previous commits so that I could correct the merge conflict.

One thing that makes this confusing is that there are two different configurations with similar-sounding names. There’s -s, lowercase ‘s’ for --signoff, and then there’s -S, uppercase ‘S’, for --gpg-sign, which is what this is about.

git --signoff (lowercase s) adds a line to the end of your commit message saying you are who you say you are. Basically, tracking who did what. It has to do with permissions and licensing, see: Developer Certificate of Origin. See: this StackOverflow thread.

If you commit some code to a project, and then it turns out that you didn’t have the rights to that code, like it’s copyrighted or something, this --signoff says that you take responsibility for the commit and certify that you are the author.

git --gpg-sign (capital S) adds your GPG (or SSH) signature (and a timestamp) to the commit using your private key which can then be verified using the public key. Basically, certifying that the document is authentic and hasn’t been tampered with. Here’s The Gnu Privacy Handbook.

So, back to Node, I had a slight fear of messing things up on a public forum with a project that I’m sort of ga-ga about. I didn’t want to make things worse when it’s already not working out for me.

And then I found another (what I thought was a) mistake in that same article, the author was talking about computational complexity but the link pointed to this Wikipedia article on time complexity, so I changed that to point to the this computational complexity page. But maybe the author meant to link to the time complexity page.

When you push to the same branch on GitHub that already has a pending pull request, it automatically updates the pull request to include the new changes. But what had happened was other people had made changes to the repo that had already been merged, so my branch was way behind.

Then after a bunch more time had gone by, I tried updating my branch using GitHub again. When you’re on your repo, on GitHub, there’s a little notification thing that says something about the repo is behind main, or up to date with main or whatever. And there’s a button that says Sync fork. If you click Sync fork, there’s an option to update your branch, basically pulling all the changes from main. I think I did that too, causing another conflict, mucking things up even more. I think that’s how it went. Like I said it’s been a while so I forget the exact details.

Overall, it was a mess. I think I could have rebased and got it sorted out, but since the changes were so minor it was easy to just start over, I ended up closing my pull request and opening another one, this time making sure my commit was signed. Here it is right here.

Thank you for reading and have a great day!