Contributing A Larger Feature To An Open Source Project

This week, we were tasked with implementing a larger feature than before, and to do so in an entirely new repository. While contributing to a repository we've previously worked on is acceptable, the goal of this course is to keep contributing to different repositories. This way, we become more comfortable with open-source contributions and reading different codebases.

Additionally, we were required to review the same feature, but contributed by someone else to our own project!

The feature involves enabling the tool to process a TOML file that contains the configuration options for the tool. This is a great idea, as our tools now have multiple options, and constantly specifying these options through the CLI can be inconvenient. These include settings such as the base URL, the API key, the temperature, and more.

Contribution to explainer.js

The tool I chose to contribute to this week is explainer.js, which is a tool that processes files and outputs the code blocks along with in-line comments as explanations.

Before tackling this feature, I went shopping for an open-source library that parses TOML files! I decided on j-toml, which is very easy to use, lightweight, and gets the job done! Afterward, I created an issue on the repo, detailing exactly what should be done and how it should work.

Now that I knew what tool I wanted to use, it was time for code reading!

After reading through the code, I knew exactly where the new feature needed to be plugged in to work! The code was well-structured and easy to read, and it was also very well documented.

My approach was simple: first, find the file in question, which in this case is a file in the home directory called .explainer-config.toml. Second, try to parse it using the TOML parsing tool mentioned above. Third, feed any options specified in the TOML file into the tool. Fourth, ensure that any options provided in the CLI override the options in the TOML file.

After seeing the folder and file structure in the project, I created a TomlChecker function, which reads and processes the TOML file if found.

Then, I returned the object that represents the processed TOML file, and in index.js, I simply gave precedence to the CLI options if they were given; otherwise, the TOML options were prioritized.

That was it! I created my pull request -- Overall, it took under an hour to finalize this feature, mostly because the code was very readable and easy to maintain, scale, and add features to!

For finishing touches, I added JSDOC comments for my function and newly added code. I also updated the README.md file to explain the newly added feature.

The reviewer had some nitpicks here and there—some typos or preferences—and I addressed every requested change with its own commit.

Contributor Review Approach

The person who added the above-mentioned feature to my project is Cleo Buenaventura. First, he created a very detailed issue on my repo, which clearly explained what the new feature is and how it's supposed to work. Then, he created a pull request with the changes. The solution worked as expected immediately; however, I had some requested changes, such as changing the name of the TOML file from .options.toml to .optimizeit-config.toml—nothing major.

To continuously test his changes, I created a tracking branch, which streamlined the way I could pull his changes and test them locally.

Cleo reused some of my code to accomplish his task and wrote as little new code as possible to achieve it—exactly what I would have done!

Now, OptimizeIt can have a TOML config file stored in the user's HOME directory. The tool automatically recognizes it if it exists and uses the user's saved configurations! This makes the tool much easier to use, as one would not have to keep providing the config options every time they want to run it.

What's Next?

This week's lab has certainly prepared us to start contributing properly to open-source projects by having us mimic how it would be if we contributed to someone else's repo or if they contributed to ours. In the coming weeks, I plan to start contributing (not just typo updates) to other open-source projects, and I now have all the tools I need to do so!