Contributing to Open-Source Walkthrough Part 2

5 min readApr 28, 2019

Working on the issue

Now that we found an issue to contribute to, we can begin the real work!

Here is the link to the issue, and a screenshot of the issue below for reference:

Keywords: custom bundling, webpack, date, version, param

I create a fork of the original repository where I will start development, and checkout a new branch called “add-banner-for-custom-bundle.

Reading documentation

Reading documentation is the first thing I do when I work on a project. Projects usually have documentation in the README.md or on their own website. I look through the mathjs docs to get a better understanding of what the project is about, and maybe clues about the issue that I’m working on.

I end up finding the part about custom bundling that was mentioned in the original issue:

I only have a slight understanding of bundling and am not that familiar with webpack, so I decide to look through webpack documentation a bit as well. Note: This is why it’s fine to pick an issue that you may not be that familiar with. You can always look up documentation and learn more in the process. Working on open source isn’t just about contributing, but learning along the way as well.

Now that I have enough general knowledge about webpack and the project, I’m able to begin replicating the issue that the author, zhy0, was talking about. josedejong also helps me better understand the problem/solution with his comment as well:

Hmm, seems the problem is that the default placeholder values aren’t replaced properly

Building the project

I notice there is a package-lock.json file in the project, which means I should do npm install rather than yarn.

npm install generates package-lock.json, yarn creates yarn.lock

After I install the node modules, I look inside the package.json folder for available commands:

There doesn’t seem to be a “start” command, which makes sense for a npm package. The “build” and “build-and-test” commands look like the ones I need for replicating the issue. Usually the CONTRIBUTING.md file should also have this kind of information.

Understanding the bug

After the above steps and looking through the codebase a bit, here is what I understand about the bug:

If I do npm run build, it bundles the project and puts the compiled files in the lib folder. In lib/header.js however, the “@@version” and “@@date” placeholders are not replaced with their actual values:

lib/header.js, placeholders are not replaced.

These are what the values should look like, inside dist/math.js, which josedejong said was correct:

dist/math.js, version 5.9.0 and date 4/24/2019

It seems like whatever method, the project is using to replace the placeholder values in dist/math.js, should also be done to lib/header.js as well.

Finding a solution

The command “gulp” is actually being run when I do “npm run build”. I’m not too familiar what gulp is, but it seems to be creating the dist and lib folder.

I spend some time reading gulp documentation..

Gulp docs mentioned that projects should have a gulpfile.js, which there definitely is. As I read through it, I find the line of code that is directly tied to the “gulp” command:

From what I learned in the gulp docs, each of the tasks here, like bundle, compile, minify…, are being run one at a time when I run the command “gulp”. I look at the code logic of each task and come up with the following findings:

The “bundle” task bundles all of the files in the src/ folder into math.js and math.min.js files inside the dist/ folder. This is how the dist/math.js we saw earlier was generated. One of the intermediary steps in the task, called createBanner, is editing the header.js file and replacing the placeholder values.
The “compile” task compiles all javascript files in the src/ folder from ES6 to vanilla Javascript (only vanilla JS is supported by all major browsers) and places it in the lib/ folder. This task does not go through the createBanner step of replacing placeholder values.

Here is the createBanner step for reference:

The solution to the issue now seems apparent. I just need to add the createBanner step to compile task, which is almost what I do. Instead, because of the way the compile task is written, I decide to write and add another task, “writeBanner”, that applies createBanner to the lib/header.js file.