Participating in Open Source

This is the first time that I have ever worked with open source tools to participate in and contribute to projects outside of my own.

This small assignment was being worked on simultaneously with the 0.1 release of our SSG tool. The assignment, in basic terms, asked us to let somebody review our code and file issues or PRs to the repo, and we should also do the same with that person's project, also hosted on GitHub.

Setting up

My professor helped us to sort ourselves out. I found my partner thanks to the professor's suggestion, as I was not looking for any particular project style.

My partner developed his SSG on TypeScript. This meant that I had to install Nodejs on my Linux laptop, which is not a big deal to do with a package manager. However, my package manager references to an old version of Nodejs, specifically Nodejs version 10. Of course, I had to install the precompiled binaries from the Nodejs website with the most updated version, which was a little bit of hassle.

After setting the project and installing TypeScript globally, I was set to test my partner's code. I went to his GitHub README, use his command and run it... only to have an error because the ts-node command cannot be found.

This was an error on my part. While I had installed the typescript compiler, I did not install the program that helps me to run typescript without having to transpile to JavaScript beforehand.

After that, I got on testing, which took more time than I thought it would. I had to write detailed enough issues on his GitHub repo so that he could reproduce the error on his part.

Filing Issues

I managed to file 5 issues:

• Cannot run project with ts-node: this was the only issue that surprised me, since I did not know what ts-node was, and I was not sure if it was an issue with my environment or the project's. Turns out it was an error on my end, but the project maintainer updated the README to improve the documentation regarding ts-node being used as a command.
• Unclear error message when entering nonexistent file name: this was an issue related to user experience. I wanted to try whether the program would detect that a file name did not reference an existent file, and, while it did, it did not display a proper message. After a while, though, my partner promptly changed it to a more understandable message.
• Title and h1 empty when title in input file is not found: this issue was related to the option title feature that our professor prepared for us. When I entered a file without a title (that is, the first line is not followed by two lines), the project would display empty <h1> and <title> elements. Since this was considered an invalid HTML file, my partner tweaked the implementation to not add such elements to the file in the case they were empty.
• 'false' is inserted despite input file being valid: this issue was related to a mysterious 'false' string being added to the generated files. My partner fixed it soon after.
• Unfriendly error message when file does not have 'read' permissions: this issue was somewhat tricky. Since you'd need to have a file that does not have permissions to read, it might be considered far-fetched to have such a situation at all. Thus, my partner disregarded it as unimportant for now.

Issues on my project

My partner also filed some issues:

• Incosistent spacing, and comma: Some formatting issues related to my files. For some reason, my text editor's extension was not formatting my code properly, so I ended up formatting the file in a really inconsistent way. At the end, I filed an issue on my own to remind myself to add a pre-commit hook that would run a formatter and linter.
• Potential improvement: Some discussion regarding the use of iterators. I would have to admit, iterators in Rust are very fitting in the unpredictable performance department. I have answered some of my partner's concerns, but I have not closed the issue yet, since I would like to research more on the iterator deal.
• Non-.txt files are also processed: this issue was related to a bug I had where I was not filtering the files by their extension, and thus processing files that may or may not have a textual format.

While I could not fix all of the issues, I feel very accomplished with the progress I have made so far with only 4 issues filed in. I am very pleased that I could fix the issue with the filtering of the text files, although it took a while to fix since I was also implementing a feature for the project.

I learned that testing is super hard, and writing automated tests that could test for most of your features are indispensable. I also learned that productivity can increase if the tools that we work with can help us to be more organized and keep track of the progress we have.