DEV Community: JLi

Release 0.4 - Release

JLi — Sat, 11 Dec 2021 01:44:33 +0000

This week I finished all of the issues I was working on for my 0.4 release assignment.

Issues	Pull Requests
#111	PR #139
#122	PR #140
#123	PR #141
#127	PR #146

I think I was able to do a good job meeting my goals I gave myself in my planning phase of this release. I was able to finish the issues well on schedule while balancing my other courses like I hoped and I was able to properly audit and fix both issues #122 and #123 without needing too many changes after review. What I learned from those two issues is the importance to read and checkout other issues/pull requests, especially for smaller repos. As I was told in the review for both my issues, I learned that the project recently made changes with how we would format the frontmatter. In PR #142 we no longer use the slug for pages due to inconsistency with links and we also need to include a description to follow the standardized Frontmatter as updated in PR #143.

So I updated the Frontmatter to match the new standard, removing the slug and adding a description:

---
id: text-files
title: Text Files
sidebar_position: 1
description: Stream data using standard library functions to access persistent text.
---

While it is fine to simply communicate with other devs to learn about changes that are made, and by no means are you expected to know absolutely everything that is happening in a project, its still very helpful to checkout other pull requests and issues occasionally to see if any significant changes are going to be made. But most importantly of all its best to simply keep up with group communications, most projects will have a Discord or Slack group to communicate with all the developers working on the project. Because generally standardization changes like this would be discussed/announced. But I think occasionally reading other issues/PRs is just a good skill to practice for any developer working in open source.

As for my Issue #127, I was supposed to add some CSS that would make all tables generated from the markdown files to be centered. I have taken several web development courses before but CSS was never a main focal point in them, rather it was more of a side lesson. So I never really had much confidence in my CSS so I didn't really know how to tackle this issue. HumpD my professor, gave a suggestion to wrap the tables in a custom <div> element with a class so we could center the tables easily in the global CSS. I had trouble figuring out how to do this because I wasn't sure how to get the markdown tables wrapped globally without manually adding a <div> to each file. After some searching I realized that I could simply apply the CSS to <table> elements directly instead of a wrapper. So I tried to do the following:

table {
  margin-left: auto;
  margin-right: auto;
}

However, for some reason the tables were not being centered even with these properties. So I was wondering if I actually had to wrap the tables after all. Thus I asked my professor how I would go about doing so, but he showed me that I was missing another property to center the tables.

table {
  margin-left: auto;
  margin-right: auto;
  width: fit-content;
}

By adding width: fit-content; the table's width would be properly calculated and would in turn allow both margin properties to be applied properly. That allowed the tables to be centered. So I learned that to center objects using CSS the width is important to be determined.

So throughout my PRs I was able to solve them by either referencing other pull requests from the community, getting reviews to my pull requests, or by discussing in the comments with other developers how to make some changes. Communication is a very vital part of open source and it is something I really appreciate a lot. I usually try to solve things by myself through trial & error and google searches, but having a community you can go ask for help is incredibly nice to have to fall back on, especially when some issues/questions can be incredibly specific to a project. All in all this was a great learning experience for me developing in open source. So until next time take care!

Release 0.4 Progress

JLi — Thu, 02 Dec 2021 21:25:06 +0000

So this week I continued to work on the issues I collected from the previous planning week. I found that the progress of auditing and fixing the pages were a lot smoother than the first time I did it in my Release 0.3 assignment. I was able to have a better idea of what to look for and I was also able to reference the pull requests of what many of my classmates did for their audits. For example, in my first PR I didn't know how to make the Frontmatter for the markdown file, but I learned that from one of my reviews what it looked like.

---
id: data-conversions
title: "Data Conversions"
sidebar_position: 3
slug: /resources-appendices/data-conversions
---

That made creating the Frontmatter much easier this time because I knew what I was doing and I also could double check with the other audited pages in the chapter to see if the slug was correct.

Another thing I didn't have to audit in my 0.3 PR was markdown tables and code blocks. The computers.md file that I audited in 0.3 did not have any tables or code so I never had to audit them. However, one of the PRs I reviewed before did have both so I was able to reference the fixes they made to also make similar checks for my pages.

The final significant change I had to fix were quoteblocks that used >. I had to change these to Admonitions, originally I did not really know what these were. However, from PR #84 I learned how make Admonitions in markdown:

:::note
Notice how the newline character (`'\n'`) (which was assigned to the tax **status** variable) places the closing parenthesis on a newline.
:::

So far I have accomplished my goal for this week and was able to complete the three issues I wanted to complete for this week. Now I just need to wait for those to get reviewed and make any fixes that my reviewers find. Hopefully I managed to do a better job this time and have less mistakes that I missed, if so then that's my other personal goal achieved. While waiting for that I will continue to work on my final issue, so until next time take care!

Release 0.4 Planning

JLi — Sun, 28 Nov 2021 21:14:26 +0000

For my 0.4 release we were assigned to continue our venture into open source repositories. For this release I decided to continue working on the Seneca IPC144 repo because I had gotten to know the project better from my 0.3 release and I wanted to explore more of how the website worked. I also learned a lot from taking a look and reviewing my peers' PRs in that repository so I think this time around I could do a better job.
I selected 4 issues that were within the same area:

I plan on going through each issue one-by-one in the order listed because I think as I work on one it will help me get a better understanding of how to take on the next. My goal is to finish the first three issues for this week and then to begin figuring out how to achieve a solution for issue 127. For my audit and fixing issues I will use the knowledge I gained from my previous audits/reviews of audits, my goal is to attempt to fix the page so when it is reviewed there will be if not none then, less mistakes than I had the first time I made an audit. That is the basic plan for my release 0.4 we shall see how it goes the end of this week. So until next time take care!

Releasing LENNAH

JLi — Fri, 26 Nov 2021 23:08:29 +0000

This week we got the chance to learn how to package and release our SSGs. For my release I decided to use conan as my package manager and GitLab as my package repository. In order to make my package I had to do a few steps first, I needed to install conan and cmake so I could run the commands. I already had cmake installed from testing Andrew's SSG so that was nice. Then I had to make a new GitLab account and link it to my GitHub account so I could import my repo over to GitLab.

Steps for packaging and deploying to repo

First I had to create a new Conan recipe.
```
$ conan new LennahSSG/1.0.1 -t
```
Then a package for the recipe.
```
$ conan create . LennahSSG/beta
```
The next step is to add a global remote that will allow conan to connect to your GitLab repository. This step requires you to find your project ID, which can be found in the Settings -> General page of your GitLab repo. It will be near the top of the page beside the repo name.
```
$ conan remote add gitlab https://gitlab.example.com/api/v4/projects/<project_id>/packages/conan
```

Once that is done you need to authenticate your connection. You can provide a few different options.

$ conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token>

Finally I uploaded the package to the package repository by using the following command:
```
$ conan upload LennahSSG/1.0.0@LennahSSG/beta --all --remote:gitlab
```

It is important to add the --remote:gitlab part otherwise it will go to the default conancenter remote. I had some trouble figuring this out, so this we definitely my "ah ha!" moment. You can also set the gitlab remote as the default instead by using:

$ conan remote add_ref LennahSSG/1.0.0@LennahSSG/beta gitlab

(Obviously replacing LennahSSG with your own project name)

Conan is nice because I didn't have to modify any of my existing files, by running the commands it added any necessary files on its own.

Testing the installation of the package was pretty easy to do, I had my friend Raymond who doesn't have direct experience with C++ or using Conan, but with some programming experience with web development, test the process. All he had to do to add it as a dependency was add a new text file to a project and run a few commands.

He added a 'conanfile.txt' file with the following inside:

[requires]
LennahSSG/1.0.0@LennahSSG/beta
[generators]
cmake_find_package
msbuild
make

Then he ran the following commands:

$ conan remote add gitlab https://gitlab.example.com/api/v4/projects/31641611/packages/conan

$ conan install LennahSSG/1.0.0@LennahSSG/beta --remote=gitlab

$ mkdir build && cd build

$ conan install ..

$ cmake .. && cmake --build .

He was able to install LennahSSG as a dependency for his project and could use it in it. You can checkout the package here.

It was an interesting process making a release, I think for future project I would want to try out using other methods as well to see if I find one that I like more or find easier. Because while I did eventually manage to figure out how to create the package with Conan, it was still a bit difficult to figure out how and follow the documentation. It also has a lot of commands you would need to remember, so maybe there are easier options to use. If you want to read more information on how to publish, install, or run packages using conan checkout these docs: publish & install, running. Until next time take care!

Reviewing PRs

JLi — Sat, 20 Nov 2021 03:59:46 +0000

Our final task for release 0.3 was to review two PRs made by our peers. The two PRs that I reviewed were from the IPC144 repo, just like the PR I made. I helped do reviews of PRs that were also auditing and fixing markdown files. You can check them out here and here.

The process I took was slightly different from what I did for my own pull request. First I took a look at the changes that they made in their PR. I would check every line that was modified and run that against the checklist to make sure that it matched the changes needed. Then I would just read through them normally as well to just check for any human error. Afterwards, I copied their updated markdown and tested it locally on my own machine to do my own audit of their audited version to see if I could spot any issues. I checked both the raw markdown file and the website version just like my own PR. Then I ran it through Lighthouse and Web Hint to check for any issues. Finally double check for any issues with light/dark mode and the mobile version of the webpage.

Both of the PRs I reviewed were very well done and thorough, they had very minimal errors to them and I was really only able to be nitpicky with one spacing mistake. It was interesting to see how different people approach the different changes such as alt text for images. While there is a best way to describe an image I was having some trouble naming some of the diagrams in my own PR but seeing how other people approached it allowed me to learn from their methods. As I stated in my previous blog post, this is really the power of open source allowing us to pool together our collective knowledge and methodologies, in turn making each other smarter and better. Anyways that's all for now, so until next time take care!

PR 2 for release 0.3

JLi — Sat, 20 Nov 2021 03:40:44 +0000

For my second PR, I worked on Seneca's IPC144 Course Notes website. This is a docusaurus created website that has markdown files for chapters taught in the IPC144 course. This was a cool one to work on because I recognized a bunch of the notes and diagrams from one of my first courses at Seneca. The issue I was helping fix was a massive list of markdown files we needed to audit and fix. So I helped out by working on one of the markdown files in a separate issue.

We were given a checklist of stuff we would need to check for and fix. This included things like formatting adjustments, typos, fixing clarity, adding links to connect the notes better, running the website through testers, etc. For my pull request I just went through the document both as the raw markdown and the ran website versions to double check for any errors, while going down the checklist to make sure everything looked correct. Auditing took a surprisingly long amount of time and even then afterwards I was given some very good reviews that helped me fix a few things I didn't catch the first time. It really shows the power of open source, where even after spending hours auditing you can easily still make mistakes, either by tunneling on some stuff, or just missing something, or even not knowing about stuff. You can learn a lot from other people giving a review to your pull request. I didn't know about docusaurus' front matter implementation so getting a review teaching me about that was really cool.

It was also cool to learn about Lighthouse and Web Hint. I never used either before but now that I know of their existence I will definitely use them in the future for any web projects that I work on.

In the end I was able to make changes to the markdown file, and adjusted to match what feedback I received from my peers. The changes were successfully approved and merged into the main branch.

PR 1 for release 0.3

JLi — Sat, 20 Nov 2021 03:11:10 +0000

For our release 0.3 project we were to make a pull request for a external project outside of our class's repos and one pull request for an internal repo. For my external PR I worked and still am working on a library project that my professor maintains outside of Seneca called Filer. Filer is a drop-in library that works like node's fs module but for browsers. The issue I was working on was making a migration of parcel 1 to parcel 2.

I have never done a migration before so I figured it would be a good learning experience and also something not too complicated to do. Turns out despite it not require too many lines of code it can be more complicated than expected. I was able to follow along their migration instructions to update any lines of code that needed changing. Such as updating <script> to include a module type where needed.

<script type="module" src="../node_modules/chai/chai.js"></script>

I also had to update the package.json with new arguments in scripts, and provide new properties to it such as target and paths to specific files.

The complicated part came in when I tried to test the program after the migration changes. For some reason parcel 2 was having trouble seeing built-in node_modules types such as buffer and path. It would give this error when tested:

$ npm test
Building...
× Build failed.

@parcel/core: Failed to resolve 'path' from './src/path.js'

  C:\Users\Joshua\Documents\GitHub\filer\src\path.js:12:26
    11 |  */
  > 12 | const nodePath = require('path');
  >    |                          ^^^^^^
    13 | const filerPath = Object.assign({}, nodePath);
    14 |

@parcel/resolver-default: External dependency "path" is not declared in package.json.

  C:\Users\Joshua\Documents\GitHub\filer\package.json:49:3
    48 |   },
  > 49 |   "dependencies": {
  >    |   ^^^^^^^^^^^^^^
    50 |     "buffer": "^6.0.3",
    51 |     "chai": "^4.3.4",

  ℹ Add "path" as a dependency.

This would require adding the dependencies as external dependencies. But that wouldn't be what we wanted to do because of outdated versions. We wanted to use the versions that already existed inside of the node_modules folder. Thus, I spent hours trying to find the solution to our problem. Through this I learned that GitHub had built-in FAQ sections and that allowed me to easily browse through other people's questions and issues. I managed to find a similar issue where the person's node_modules were seen as external, but after trying their solution it would still give the same error. Thus, after searching issues and questions I made a new issue report to hopefully get the answer.

This PR is still a work in progress, but I learned a lot about migration and learned more about using GitHub as well in the process. Despite it seeming like a pretty simple issue on paper its cool to see that I was able to learn some stuff and gain experience with this type of task. If any of you reading want to take a look at the issue feel free to do so. Hopefully I will be able to make an update soon once I get a response for my issue, but until then take care!

Adding Continuous Integration

JLi — Fri, 19 Nov 2021 23:51:56 +0000

This week we learned how to use the tests we made last week and directly implement them into our GitHub repositories. By adding continuous integration we no longer have to run our tests manually every time we make a new commit to our repos, instead it does it automatically every time we make a new pull request or merge into the main branch!

Since I've been coding my project using Visual Studio I used MSBuild as my workflow template, because Visual Studio uses MSBuild to compile and build projects when running the built in debugger. So that makes it easy to make sure that it will compile properly on GitHub's side. Other than that decision it was really easy to setup the YAML file, I just needed to add two lines:

run: msbuild LennahSSG.sln /p:OutDir=D:\a\LennahSSG\LennahSSG\LennahSSG

to build the executable and

run: D:\a\LennahSSG\LennahSSG\LennahSSG\LennahSSG.exe -t

to run the test.

After setting up my own CI and ensuring everything was working properly I teamed up with Andrew Tassone to work on his SSG. I added a new test case to his that would check for proper markdown conversion with the <h1> tag, you can check out the PR here. It was a bit more difficult to add a new test case to a different project, mainly because his structure for his project was still a larger collection of code, rather than many smaller functions. He did not refactor his project like I did so I had to think of how to test things with the project in one piece.

After setting up CI for the first time it is incredibly convenient. It is a bit annoying to set up tests the first time and then making sure they cover as many things as possible but once you have it up and running. Turning tests into CI is very simple to do and in the long run it makes adding new features and just making changes in general so much better, because then you will know when something breaks and where it breaks.

Adding tests to LENNAH

JLi — Fri, 12 Nov 2021 04:33:33 +0000

This week we learned about built in unit tests and E2E(end-to-end) testing for opensource projects. Its a really great way to easily test your code to make sure everything is working as intended without having to check it all manually after every modification. Instead you write code that will do all the testing for you, so you can check everything works with just a click of a button, or in my case a quick CLI command.

Since LENNAH is written in C++ I had to look around for a good unit testing framework and I came across Catch2. Catch2 is a very easy to use testing framework because all you need to do is add a single header file to your project then #define and #include it! This was the main reason I wanted to use this framework, because I saw a lot of people online recommend it since it is quick to set up and easy to use. And they are absolutely right about that, it only need two lines of code to set it up.

#define CATCH_CONFIG_MAIN
#include "catch.hpp"

That's all you need! But if you have a main() already and don't want to use the auto-generated one that Catch2 creates. All you need to do is change the #define:

#define CATCH_CONFIG_RUNNER
#include "catch.hpp"

This will allow you to run the tests from your own main function. You just need to call it with Catch::Session().run();. So you can set it up how you want. What I did was add another command line argument --test or -t that would run the test. Very simple!

To create tests all you need to do is add TEST_CASEs like so:

TEST_CASE("Inline Code function", "[code]")
{
    Formatter test;
    SECTION("Strings with ` markdown")
    {
        REQUIRE(test.inlineCode("`Hello World`") == "<code>Hello World</code>");
    }
}

The first string is the name of the Test Case and the second one with the [] is the tag. Then you just add REQUIRE statements to check for correct results. You can also use SECTION to make specific sections for each Test Case.

While I was creating these test cases I actually discovered a handful of smaller bugs that I didn't notice before. My formatting functions for handling markdown syntax had a few missing characters from the code that Gus created way back when he added them. It appears there were just a few copy pasting mistakes that he left behind that I didn't catch, so the tests helped a lot with finding those. Furthermore, I learned that some of the logic with his functions was actually flawed because of the use of string::find_last_of(), this string function did not work how we both thought it did originally. Rather than finding the sequence given as a parameter it only looked at individual characters. Thus, I learned to change the code to use string::rfind() instead, which does the same thing as string::find() but from the end of the string instead.

I learned a lot after doing this, it taught me how to setup testing frameworks, and the importance of refactoring your code into smaller functions. Thankfully I made these changes previously, but now I really see the impact it made. By refactoring the code it made the task of implementing unit tests for each function 1000 times easier. I've never set up automatic unit testing before. I've only done manual testing of each function through console messages or doing code follow throughs. But this is a fantastic way to test my programs without the constant tediousness of doing it manually, I only need to make the test code once and occasionally update it as necessary. This saves me so much time and effort in comparison.

Learning how to use Static Analysis tools

JLi — Fri, 05 Nov 2021 14:33:17 +0000

So this week we learned about static analysis tools such as formatters and linters. I also got a little prior experience with using these analysis tools because of my Hacktoberfest PRs, two of the repositories I made PRs had these tools and also had bots on their repo that automatically checked that these tools were ran.

For my LENNAH SSG, I decided to use Clang for both the formatter and linter. I chose to use clang because it had both the formatter and linter in one package for C++ and it look extremely user friendly, especially their Visual Studio extension. Clang also has commands you can use in the command line to run both the formatter and linter if you don't want to use extensions. However, this took me a bit of time figuring out how to do, so I will give a quick explanation on how to set it up to simply the process.

Installing + Running Clang for Command Line

Download the build here
Then when running the installer make sure to add LLVM to the system PATH
Once installed, in the terminal go to the project folder and then you can use the following commands to format or find lint.

$ clang-format -style=file LennahSSG/*.cpp LennahSSG/*.h

$ clang-tidy --config="" LennahSSG/*.cpp LennahSSG/*.h --extra-arg=-std=c++17 --extra-arg=-xc++ --

Installing Clang Extension for Visual Studio

Open Visual Studio and go to the Extensions drop down at the top.
Open Manage Extensions and search for Clang Power Tools.
Then download and restart Visual Studio.
You will have new buttons in the top of your bar that will allow you to format, tidy, and use other features Clang provides. For more information you can check out their getting started guide on their website.

Formatting and Removing Lint from LENNAH

When I ran the formatter and linter I found out that there were a good handful of simple changes that actually made my code nicer to read. The biggest change was the use of additional whitespace before lines. Specifically for parts where I am outputting to a file using << whenever I made a new line it wouldn't line up with the first line. For example:

    outputFile << "</ul>\n"
        << "</body>\n"
        << "</html>\n";

But after the formatter it made the readability much better and more satisfying to look at:

    outputFile << "</ul>\n"
               << "</body>\n"
               << "</html>\n";

This was a small change but something I didn't really think much about because of how Visual Studio's base spacing worked. I think this is a really nice fix that improves the code greatly, even though it is just simple spacing.

As for the Linter, there was only one piece of lint in my code and it was an extra boolean variable that I forgot to remove from a previous iteration of a function. That was very nice because it was just a small variable surrounded by many other variables so it would have taken me a long time to notice that, were it not for the Linter.

This was a great learning experience for setting up Static Analysis tools, and it really shows how powerful they can be. I will always be using these tools, especially the extensions, from now on because they are so easy to use and they make quality of life so much better. The way I have been writing code before is like using Microsoft Word without spell/grammar check, literally making it so much harder for myself. So be sure to do yourself a solid and look into static analysis tools for your own projects if you haven't already. Until next time take care!

My 4th Hacktoberfest PR

JLi — Sun, 31 Oct 2021 20:19:38 +0000

For my fourth issue I wanted to find something a bit more challenging, so as I was searching around I came across a cool WIP application being created by one developer. She was creating a desktop client for Looperman, which is a cool website that houses a pro audio community that shares music loops, acapellas, vocals, beats, and much more. It is like the opensource equivalent for audio, where you can share your work and get feedback/help from others, or help others as well. This app is still in its early stages of development so I was able to contribute by adding a new volume slider feature. The issue was that whenever the user would preview audio clips it would only be able to play at 100% volume, so for user experience she wanted a volume slider to be added. This was a fun issue to work out as I have never worked with audio files in javascript, so it was a great learning experience.

There was a few things I had to do:

Add a slider for volume (HTML)
Add a function to modify the volume of the audio player (JS)
Fix the appearance of the slider to match the theme (CSS)

I ran into a few troubles with trying to adjust volume with the audio player at first, but after playing around with it a bit I learned that volume is between 0-1 not 0-100 which helped solve my major problems at first. After getting the base functionality down I needed to fix the appearance of the slider because it was just the default slider like this:

I think this step was the most difficult thing I faced, throughout my classes I never really got a lot of practice with CSS so figuring out how to customize the slider took a bunch of research. Eventually I came across a helpful video explaining how to create a custom slider. The biggest trouble I had was trying to figure out how to make the bar colour of the slider to be different from the background colour of the slider. This video helped me understand how to implement it through javascript. After finishing the CSS the initial version looked like this:

The developer stxarixdust was happy with the initial commit, but also gave some suggestions to improve it. She wanted the Volume label to be replaced with a speaker icon, and for the sliders to be right aligned. This gave me the chance to learn about feather icons, which is a really cool opensource collection of icons. They have a large library of your standard icons and also are customizable! This collection is something I will definitely bookmark for any future projects that need high quality icons.

For changing the label I wanted to take it a step further and make the icon responsive based on what the volume is at. This was a pretty simple addition since I already had a function that adjusted volume I just needed to also adjust the icon that is displayed depending on the volume. Additionally, I figured that a mute button function would also make sense to have so I added a function that simply toggled the audio player volume between 0 and the current volume when the speaker icon was clicked. So the final version looked like this:

This was a very fun PR to work on, it allowed me to learn about some features and libraries for javascript and also let me practice some CSS. You can checkout the full PR here. Until next time, take care!

My 3rd Hacktoberfest PR

JLi — Sun, 31 Oct 2021 04:12:28 +0000

For my third pull request I was actually able to checkout a project that previous students of my open source class made in this class called Telescope. Telescope is a web server and client application that is used to keep track of Seneca students' blogs; just like the one you are reading right now! Since we were eventually to contribute to the Telescope project later in the semester, I figured I should get a bit of a head start and become a little familiar with the project.

For this issue there was some problems with the validity of specific feeds. However, this issue was not easily solved because the error logging was not working. Thus, for this issue I had to help add error logging for when feeds were not being parsed. This task while is a simple task on paper was still a bit difficult for me to understand. I think my biggest hurdle for this issue was to follow along with what everything was doing. The Telescope project is a fairly large project that has a lot of parts to it so it was really easy for me to feel a bit overwhelmed. However, one of the developers humphd (who is also my professor :winkyface:) made it much easier on me by directing me to which file I would be modifying and what I should take a look at. From there I still wanted to get a bit of an understanding of what was going on so I took the time to read through the code and other files it required from. Despite me feeling very lost at first I was able to understand what I needed to do and managed to make a good pull request. Aside from a little mistake where I missed a part of the code (Whoops!) It was a simple fix where I needed to modify the signature of a function to allow error messages and then store/log the error message.

While it was a quick and easy fix, the process to get there took a while because I had a bit of trouble following along with the code. But after taking the time to read through I was able to figure out what was needed. So after this PR I think I feel a bit more confident in viewing larger projects, its important to remember that you are not expected to know the ins and outs of the entire project. Just reading and understanding the necessary components is all you really need, and you can always ask the developers for help where to look.