Livecoding: Why Contributing to Big Open Source Projects Is Still Hard [Video]

DZone 's Guide to

Livecoding: Why Contributing to Big Open Source Projects Is Still Hard [Video]

While open source projects are great, sometimes they can run into some snags. A developer shares one such experience in this livecoding session/article.

· Web Dev Zone ·
Free Resource

GatsbyJS has a buggy feature that I don't like and I'm gonna fix it! Biggest opensource project since I poked around phpBB back in high school.

I can do this!

GatsbyJS is a React-based static site generator. The reason I'm so invested is because almost everything I build with React is a static site. Landing pages, single data visualizations, stuff like that. All static.

Gatsby has a plugin, gatsby-transformer-remark, that lets you write copy-focused pages in Markdown. React gets tedious when you want to focus on writing copy.

This remark transformer comes with a feature I love: tableOfContents. Looks at your header tags and generates a table of contents. Great for making your site easier to navigate.

But there's a problem.

Table of contents uses only hash links like #this-is-a-subheading. This works great when it's on the same page as your content, but it's not so great when you put it on an index page.

Index pages are often at different URLs than their content pages. So when you try to link with just a hash, it doesn't go anywhere.

I decided to fix that and use absolute links.

So we looked at the CONTRIBUTING.md doc in Gatsby's repository, and it was wonderful. Tells you everything you need to set up a development environment so you can work on Gatsby and your test site immediately picks up on it.

  1. Fork and clone Gatsby ✅
  2. Run yarn run bootstrap

Wait... no... that didn't work. Step 2 and we're already blocked.

We filed a helpful issue complaining that nothing works and everything is broken. The command didn't run through, dependencies were missing, and everything blew up in our face.

Two hours later, we had installed some 30 missing packages and aaaaalmost got a clean yarn test run. Very important to have all your tests passing before you start poking around a large codebase.

A very helpful person named m-allanson saved our asses. They found a commit from Gatsby's head maintainer that changed something in a config - removed yarn workspaces whatever the hell that is - and it was just 23 hours old.

All our troubles were because of a commit from less than a day ago. Talk about timing!

And it was the kind of problem only a new contributor could discover. Everything worked for people who had stuff installed from before.

So... yay? We helped?

Once we got up and running, it was almost time to stop livecoding for the day. We had just enough time to figure out where in the code we're going to have to fix those links.

A file called gatsby-transformer-remark/srcextend-node-type.js.

This function ��

async function getTableOfContents(markdownNode) {
 const cachedToc = await cache.get (tableOfContentsCacheKey(markdownNode) )
 //if (cachedToc) {
 // return cachedToc
 //} else {
 const ast = await getAST(markdownNode)
 const tocAst = mdastToToc(ast)
 let toc
 if (tocAst.map ) {
 //toc = hastToHTML(toHAST(tocAst.map))
 toc = toHAST(tocAst.map )
 console.log (require( 'util' ).inspect (tocAst.map , false , null ) )
 } else {
 toc = ``
 cache.set (tableOfContentsCacheKey(markdownNode) , toc)
 return toc

Note the console.log. That's where we have to hook into the toc abstract syntax tree and change the links.

Not sure how yet, but how hard can it be? 

web dev ,open source ,web application development ,open source development

Published at DZone with permission of Swizec Teller , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}