TIL How Issue Reporting Works

Today I learned how to file issues on someone's repo. It was a very simple process, and I enjoyed it. It basically felt like peer reviewing someone's essay. To start with, I first had to find someone to work with. I did this by posting my repo to the slack chat and requesting a partner. I was fortunate enough to find someone else who was looking for a partner. After I received their repo I began testing and reviewing it.

I did come across a few issues. I'll discuss them in the points below.

1. The first issue I came across was a bug that would affect the way the program ran. A link to the issue can be found here. Essentially what the issue was is that when the user tried to copy the absolute path of a file by right clicking on the file in Windows and pasting it's path into the terminal for the program to use, like so tiller "C:\Users\marco\Desktop\College\Year 3\OSD600\lab1\tiller\file1.txt". It would produce an error. This error was ENOENT: no such file or directory, open 'til/C:\Users\marco\Desktop\College\Year 3\OSD600\lab1\tiller\file1.html'. Looking at the error, I think this had to do with the output directory being generated incorrectly when the user would provide an input path like the way I did. (I had a similar issue and that's what I had to do to solve it).

2. The second issue I found was related more with the way the program documentation was created. Based on our assignment instructions, the program must delete the output directory each time it runs. For example, if I were to convert a txt file to html, my converted file would show up in the til directory. I may then delete the txt since I have no need for it. Later in the day I may try to convert a different txt file in the same directory. Upon running the program I would notice that my first converted file is now gone, and has been replaced with the second file converted file. This can be a big issue for people who are unaware that their output directory gets deleted and may not be backing up their converted files. So I thought that the user should've been made aware of it. You can see my issue report here.

3. The third issue I noticed was the lack of code comments. Code comments were mentioned in the assignment documentation. However, even if this wasn't an assignment, I think that code comments would still be important. Mainly because this is an open source project, other people could be looking at the code and trying to find ways they can improve it or understand how it works. Some people could even be reading the source code to expand on their own knowledge of programming. You can find the issue report here.

I did file two additional issues, that can be found here and here. They are more like nitpicks in the program, which is why I didn't mention it here. Next are the issues that came up in my program.

1. The first issue found in my program was related to the way my HTML files were generated. They did not follow the proper instructions for the assignment. I think I misunderstood the tenth step, which was ensuring that every blank line is a paragraph limit. What I originally had was that at the end of every line was a paragraph limit, and then a br tag would be inserted when a newline was found in the txt file. To fix this I had to change the way my logic works for the loop where I convert the actual txt file. My original loop that would take in a line from the txt file convert it to a p tag each time the loop ran. My updated version now has a flag to see if it's in a paragraph. If the program isn't in a paragraph yet, it will start the p tag then set the flag to true to say that it is. Then if the current line isn't a new line it will append the current line to the p tag with a white space behind the sentence to help formatting, and continue. Once a new line is hit, it will close off the p tag and set the flag to false. As I'm writing this, I think I noticed a particular issue that can arise from this, so I may need to update my code so that an empty p tag isn't created.

2. The second issue found in my program was related to a success message being printed for every file in a folder that got converted. What caused this was that I was originally trying to make some kind of thing for the user to show them how many files have been successfully converted out the x number of txt files in the folder they gave as input. So this way, the user would know if something were to go wrong. However, I decided not to go ahead with this idea since my code is meant to throw an error if something went wrong during conversion. I had the success message printing in a for loop and forgot to move it out of the for loop when I changed my mind. So that's how I solved it.

3. The third issue found in my program was related the program being unable to process input from the user if the path they entered was from a file in a folder. The issue was somewhat similar to the first issue that I found in the repo that I was testing. The problem was due to how my output path was being generated. It was generating a invalid path. So I had to update the way I created the output path. This solution solved the issue. However, when I made the commit, I tested out the program a little more and realized that I was now unable to open folders. It was giving me an access denied error. It took me a little bit to figure out why I no longer had access to folders, but I realized that when I was making changes to my code I also updated the input_file variable to just take in the input_path. My code was essentially trying to open a folder for reading, which isn't possible and that's why the error was being thrown. So I made the changes to fix that issue as well so it get's the filename from the folder and opens the file in the folder for reading.

4. The fourth issue found was that my README wasn't very clear on how to run the program. I thought that my program can be executed in the terminal like this txt_to_html filename.txt. I was hoping that it can be executed like a script, so the user didn't have to type python or the .py extension to run it. However, I couldn't even get this feature to work. I followed some articles on the internet that told me how I can get that feature to work, but they didn't work for me. So for now I'll have to let the user use the program like this python txt_to_html.py filename.txt. Hopefully in the future I can get it to work.

5. The fifth and last issue found in my program was that I had a lot of excessive comments. Ironically, I created an issue due to the lack of comments in the repo I reviewed, and mine had too many. This issue was created due to the fact that when I code I like to make my code as easy to understand as possible. I also leave a lot of notes for myself in the code so I can understand what I did when I go back and look at it. However, a lot of my code is self explanatory based on variable or function names. So I cleaned up a lot of comments that did not need to be be there to make my code less cluttered and easier to read.

Fixing my issues taught me a little bit more about my own code and how I should be designing it. But it also kind of gave me an idea of how actual bug reports work in the real world, and that everyone has a different way of using programs. For example, the third issue that was found with my program, I wouldn't have known about it unless the issue was files. Since I was running my code by only handing it a folder or directly giving it a file in the current directory. So it also helped me learn the importance of having people to test your code and making sure that everything is up to par. However, the next time I file an issue on someone's repo I want to make sure that I provide the issue I created with a label. GitHub allows you to leave labels on issues to help specify what the report is about, and even though me and the person I worked with both stated what the issue was in the title of our report. Using the label feature would be beneficial.

Overall, I learned a lot from this process of testing and reviewing. It gave me a better insight into how programmers operate in the real world and taught me some stuff about how I should change my programming style. I'm looking forward to learning more about git and open source in general. Catch you in the next post!