DEV Community: Paul Kim

Adding a Continuous Integration Workflow

Paul Kim — Sat, 18 Nov 2023 04:37:03 +0000

For this week in Topics in Open Source Development we were tasked with adding continuous integration tests into an existing project. The project that I will be enhancing is til-to-html - a markdown to static HTML site generator.

Bun CI Workflow

Last week, I added automated unit tests to my project. This time, I will add a CI workflow

Up until now, whenever code was merged into the main branch, it was up to the maintainer (me) to manually run tests on incoming code. Now, a workflow will be triggered when anyone attempts to push to or create a pull request to be merged onto the main branch. As this is a Bun.sh application, I followed the official setup guide to run Bun in GitHub Actions.

The workflow file I created does the following:

Whenever someone:
- pushes to the main branch, or
- creates a pull request for the main branch…
GitHub Actions will run a job that:
- installs Bun using Bun's official setup-bun routine
- uses the latest version of bun
- installs all package dependencies
- runs a build
- runs all unit tests

If any of these steps fail, the push/pull request is rejected.

Bun CI Workflow: https://github.com/paulkim26/til-to-html/blob/main/.github/workflows/bun.yml

Adding tests to a partner's project

(coming soon)

Takeaways

This is the first time I incorporated an automatic CI testing workflow into a project. I enjoyed how straightforward and well documented the process was. Adding a CI workflow alleviates a lot of anxiety when it comes to integrating code not just from other developers, but from me as well. These are all checks and balances I would have had to worry and remember to execute myself - there's no reason not to automate these trivial tasks.

Thanks for reading!

Writing Tests

Paul Kim — Mon, 13 Nov 2023 02:44:37 +0000

For this week in Topics in Open Source Development, we were tasked with adding tests to an existing project. Here is my experience doing so.

Project Repository: https://github.com/paulkim26/til-to-html
Commit: https://github.com/paulkim26/til-to-html/commit/2a00cf69b4fab11c65baedc9ca518fe3bf36e9d6

Testing Framework

Since my project already uses Bun, I decided to use Bun's own built-in test runner. It is based on Jest which makes it easy to pick for developers familiar with that testing framework. As a result, there was no additional setup required.

Writing Tests

For this project, I added tests that test the markdown parsing modules I had previously written (source). Since each markdown parsing module accepts multiple syntaxes e.g. markdown italics can be represented as either _text_ or *text*, I made sure to test for each matching combination along with an aberrant test case (e.g. an empty string) (example).

One nice thing I realized working with TypeScript is that I don't have to write additional tests that check for strange type combinations e.g. passing a null to a function that accepts only strings, since TypeScript already blocks such cases. If I had written it in a weakly typed language i.e. JavaScript, I would have had to cover these cases as well.

Takeaways

I have only had limited experience writing tests before; this was a good experience to write some more. I was surprised to learn how verbose and comprehensive the act of writing tests can be. It is in its verbosity, however that test writing is great since it is easily readable for a human. I see no reason for any project to not include its own suite of tests, especially open source ones. I will for sure continue to write tests in all of my projects going forward.

Adding Static Analysis Tooling

Paul Kim — Sun, 05 Nov 2023 01:48:18 +0000

For this week in Topics in Open Source Development, I was tasked with adding Static Analysis Tooling to an existing project.

Project: til-to-html
Commit: https://github.com/paulkim26/til-to-html/commit/c34a0b61c28847822f6a7467f68eeaf54e08ca03

Tools Used

To automatically format and lint code in this project, I used:

I chose these as I am familiar with them and have enjoyed using them for previous projects. They are commonly used by many projects and integrate well with Visual Studio Code. Prettier is an opiniated automatic code formatter that formats all code in the same way. ESLint is a linting tool for JavaScript that is able to detect code smells and can automatically fix them too (if configured to do so).

Setting up Prettier

Note: this project is using Bun.
The following instructions are adapted from https://prettier.io/docs/en/install.html.

To setup Prettier, I ran the following to install Prettier:

bun install --save-dev --save-exact prettier
node --eval "fs.writeFileSync('.prettierrc','{}\n')"

Then I added a .prettierignore file, using the same contents of my existing .gitignore file. To format the project, I ran:

bun prettier . --write

This command is then added to the package.json file as a runnable script.

Setting up ESLint

The following instructions are adapted from https://eslint.org/docs/latest/use/getting-started.

To setup ESLint, I installed the eslint package.

bun install eslint

Then I created a .eslintrc.json file. It extends the following templates to be compatible with typescript and Prettier:

eslint:recommended
plugin:@typescript-eslint/eslint-recommended
plugin:@typescript-eslint/recommended
prettier

I customized the linting rules to fit the preset coding conventions I set in my project; I disabled the following rules:

no-useless-catch
@typescript-eslint/no-explicit-any

Then I added a .eslintignore file, using the same contents of my existing .gitignore file. To format the project, I ran:

bun eslint .

This command is then added to the package.json file as a runnable script.

Editor Integration

To integrate with Visual Studio Code, I setup a VS Code configuration file under .vscode/settings.json. This file ensures that:

Prettier is set as the default formatter for the project.
On save:
- Files are formatted.
- Files are linted with ESLint.

The following VS Code plugins are required:

Takeaways

After running Prettier and ESLint, I found many issues in my existing code, including:

Declared arguments that were unused
Extraneous whitespace
Improperly indented blocks
Missing commas

I have been using Prettier and ESLint for a while now in my own projects, but its a good idea to set it up for each project rather than globally so that:

All contributors use it
A specific version and configuration is used

Instructing and encouraging all contributors to follow the same standards I do in a programmatic, consistent way will help out immensely with the maintainability of the project.

Thanks for reading!

Hacktoberfest Recap

Paul Kim — Wed, 01 Nov 2023 07:35:58 +0000

For this month in Topics in Open Source Development, I was tasked with partaking in Hacktoberfest and submitting 4 pull requests this month.

Pull Request 1 - https://dev.to/paulkim26/hacktoberfest-week-1-33hh
Pull Request 2 - https://dev.to/paulkim26/hacktoberfest-week-2-4648
Pull Request 3 - https://dev.to/paulkim26/hacktoberfest-week-3-49id
Pull Request 4 - https://dev.to/paulkim26/hacktoberfest-week-4-ad2

Here are the big takeaways I learned…

It takes a long time to find issues to work on

There was no shortage of interesting projects to work on, but finding one to work on can be a lot of work in and of itself. Before taking on an issue I had to make sure I could even properly set it up. Some projects had extensive requirements to follow through. Others had technical issues or were buggy in a way that prohibited further enhancement for the issue. Another dealbreaker were projects that asked to be refactored entirely or have the documentation written for in post - this indicated a general lack of quality to me that was not worth dealing with.

Here are some of the repositories I passed up for one reason or another:

No response
- https://github.com/trussworks/react-uswds
Problems during setup
- https://github.com/mattermost/mattermost
- https://github.com/Xkonti/file-api
- https://github.com/JordanForeman/cf-find
- https://github.com/digitalfabrik/integreat-app#project-setup
- https://github.com/yanna92yar/open-listings
- https://github.com/beda-software/fhir-emr
- https://github.com/AnshuPathak-88825/Live-code
  - App did not work properly.
- https://github.com/harshmangalam/qwik-x/issues/64
  - App had errors fetching from database.
Felt too much like a student project
Were out of scope
- https://github.com/prasenjeet-symon/intellectia/issues/174
- https://github.com/stephane-r/holoplay-pwa/issues/32
  - Involved testing an Android version.
- https://github.com/0xVikasRushi/OpenIssueMonitor/issues/1
Involved non-coding work only
- https://github.com/YurisCodingClub/zero-minds/issues/21
  - accessibility check
- https://github.com/OpiumPay/opium-frontend/issues/2
  - readme creation
I had no idea what these projects did

You can submit a pull request right away

One thing I learned early on from my peers on our course Slack - you don't have to wait for permission to submit pull requests to an issue. You can go ahead and post one anyway and use that as a starting point for communication. This is contextual of course - certain problems require extensive communication before starting out on.

It can be fun to jump into a new framework on the fly

I experienced a lot of new tools, frameworks, libraries, architectures, and coding styles during Hacktober. The ones that stuck out to me in particular were Prisma, Svelte, Chakra UI, Postgres, simple-keyboard, Qwik, Notion, and Firebase. I didn't have to learn these tools comprehensively at the onset - I could play around and tinker with them and discover how they worked and discover how to best use them for my specific use case. I may or may not use these all in my software development career but the skill of picking up, well, new skills is something I can hone over time.

The open source community is really nice

The project maintainers I have interacted with were pleasant and professional to work with. They would go over my code extensively, give meaningful feedback, take and accept my suggestions - just overall be very easy to work with. Looking at other people's discussions, there was never any vitriol or poor communication skills on display between any parties (at least none that I've personally witnessed). Everyone has the same goal on a project and it's great to see everyone working together towards that.

Small issues can be a surprising amount of work

An issue may seem straightforward at first, but I discovered some of them can go quite deep. For example, on one of my issues I had to implement a "Forget Password" page. At first it sounds like its just one new view to add, but the more I thought about it the more the work revealed itself - I had to introduce tokens stored in the database, I had to refactor existing code that overlapped with my aims, I would come across bugs in the code or in the tools I was working with. Thankfully, project maintainers can offer great insight and suggestions.

Hacktober was really fun! I highly suggest everyone who hasn't already to give it a try next time.

Thanks for reading!

Hacktoberfest Week 4

Paul Kim — Wed, 01 Nov 2023 07:35:03 +0000

For my fourth and final Hacktoberfest PR, I worked on a project called YABin by Yureien.

Project Repository: https://github.com/Yureien/YABin
Issue: https://github.com/Yureien/YABin/issues/19
My Pull Request: https://github.com/Yureien/YABin/pull/29

YABin

YABin is "Yet Another Pastebin" that seeks to add features not found in other similar applications, such as:

Modern and minimal UI (This site's design was inspired by bin).

Optional end-to-end encryption (we're using AES-256-GCM) with optional password protection (using PBKDF2).

Syntax highlighting (using Prism) that supports 297 languages.

API support to create and get pastes from command line.

View raw pastes. Normally, encrypted pastebins do not have this. With this site, you can either get the Base64-encoded encrypted paste, or decrypt it on the server side (even with the password) and get the raw paste.

Keyboard shortcuts!

And of course, being fully open-source and easily self-hostable.

NEW Ability to edit pastes after creation, and a dashboard for viewing all your pastes.

Comes with a CLI tool to create and read pastes from the command line!

It can even be run on edge servers and in serverless environments!

It is a Svelte web application, can leverage any type of database (supported by Prisma). Users can create "pastes" to share with other users, set their time of expiration, they can be encrypted, be destroyed after being read, and users can create accounts.

You can check it out here: https://bin.sohamsen.me/

Issue

The issue asks to implement a page for the user to reset their account password. Breaking this down, the flow would look as such:

The user clicks on a "Forgot password?" link in the login page.
Present user with a form to enter their username or email.
The user clicks submit.
The server finds the email address associated to user in the database (if just the username was provided).
Generate a password reset token, overwriting any existing ones.
Send an email to the user with a link to reset their password i.e. "Click this link to reset your password".
The link takes the user to a page to enter their new password.
Check that the password reset token exists and has not yet expired.
If the provided password is valid, update it.

This entails:

The addition of two new routes
A password reset token database entity

Setup

The first step was to get the project running. Following the project's README, I had to set up some kind of database; Postgres was recommended. I have not worked with the Prisma ORM before but I quite enjoyed using it. After setting up a Postgres database and user, all I had to do was migrate the schema defined in Prisma into my database and it would set it up accordingly. Prisma is flexible enough to work with many different types of databases, so it didn't have to necessarily be Postgres. It was interesting to look through through the Prisma migrations files in the project, they were incremental SQL statements that collectively formed the instructions on how to completely rebuild the database from scratch (source).

Svelte

Another new thing about this project for me was using Svelte. Svelte is a framework I have only heard recently as a "down to earth" experience that felt like one was coding in the good old days where there was less abstraction in web development. The first thing that struck out at me was the file naming convention - a view was named +page.svelte and server code was placed in +page.server.ts files. I hadn't seen any frameworks that use + signs in their pathnames - I would've thought this would cause issues in certain environments. The front-end syntax resembled Handlebars.js, a similar HTML templating library I learned a while ago.

The "Forgot Password" Page

Here's the "Forgot Password" page I wrote - src/routes/(auth)/forgot-password/+page.svelte and it's accompanying server code - src/routes/(auth)/forgot-password/+page.server.ts. If the MAIL_ENABLED environment variable is set to false, the page will simply redirect the user to the root route (since email is disabled), otherwise the page loads normally. I set up two Svelte functions a load function which is called upon page load and actions which defines i.e. a callback function when a form is submitted. The page asks for a username or email of the account to reset the password for. It then checks if that user exists, then sends an email to the one registered for the user. It pulls the user data with Prisma's findFirst method which was very straightforward to use. It was nice not having to worry about database-specific methods and just use a generic one that'll work for all of them.

Nodemailer

I set up a sendRequestEmail function (source) that calls a generatePasswordResetToken function (source) that upserts a password reset token into this database for this user. It then constructs a URL and sends an email using the nodemailer library which I've used before. The SMTP service I had used before had gone defunct unfortunately and the free SMTP server options had features I could not overcome (i.e. requiring a legitimate business identity and address). I ended up using a spare Gmail address configured with an app password. I used 10minutemail to generate some email addresses and everything worked great. The tokenized URL was sent to users.

Processing a password change

This URL would point to a new reset-password route (source). Upon page load, it will check to see if the URL contains query parameters for the user ID and the reset token that was passed via the email. If one is missing or invalid, the user is blocked from the route. If both are present and verified, the page loads. The user will see two fields - a field to enter their new password and another to confirm. Upon page submission, the server will validate the password (i.e. are of a sufficient length), generate a password hash, delete the reset token, and then redirect the user to the login page (source).

I originally intended for the user to stay on the page with a confirmation message i.e. "Your password has been successfully updated." However, when I delete the reset token from the database, it noticed that it forces a page reload, which is problematic since the token will no longer exist and the route will be invalid. I attempted to suppress this page reload but was unable to find a way to do so. I am still not sure how to overcome this behaviour.

Takeaways

This project was fun to work on. The new technologies (Svelte, Prisma) were fun and straightforward to work with and the project was organized well. I had to refactor some existing code to make it work (source) - I tried to make smart, surgical changes that impacted the existing code as little as possible. I learned that it can be pretty easy to learn and work with new technologies on the fly - they all tend to follow similar features and workflows that can be worked out even without prior knowledge.

Thanks for reading!

Hacktoberfest Week 3

Paul Kim — Wed, 01 Nov 2023 07:34:36 +0000

For my third Hacktoberfest PR out of a required four, I continued worked on a project called Ordspel by avikantz.

Project Repository: https://github.com/avikantz/ikea-word-games
Issue: https://github.com/avikantz/ikea-word-games/issues/41
My Pull Request: https://github.com/avikantz/ikea-word-games/pull/42

Issue

A quick recap - Ordspel is a collection of linguistics games based on furniture names from the Ikea store. You can play it here - https://ikeawordgames.com

What was interesting was that not only was this a project I had previously worked on before (my previous PR), but this was an issue I posted myself. While working on disabling the non-solution characters in the Jumble keyboard (issue), I noticed that the keyboard would act funny. If there were more characters entered than allowed in the virtual keyboard, the characters would "overflow" and persist beyond the normal limit. It made for an unsatisfying user experience since you couldn't tell the bug was happening just by looking at it - you'd only realize the issue when you tried to backspace.

The Solution

Coming fresh off the previous issue, I was familiar with this project already (you can read my experiences here). The solution was to truncate the stored input value in the keyboard component (accessed via the keyboard component reference) if the value exceeded the maximum input size (link). This was an unfortunate circumstance of the keyboard's input value "desynchronizing" from the rest of the code. Since this input value was not maintained using React state but rather the simple keyboard API, there needed to be some extra checks and balances to make sure it was properly being watched.

Takeaways

It surprised me that such a bug was there and unreported until I discovered it. It really goes to show how selective all of our perceptions and experiences around the same software are. We all experience software uniquely and catch onto certain issues that other's won't know. It goes to show the power of the open source community and having an extra set of eyes watching over one's shoulder 👀.

Thanks for reading!

Adding a search feature to my app

Paul Kim — Mon, 30 Oct 2023 04:59:34 +0000

For this week in Topics in Open Source Development, I was tasked with performing a code reading of a specific feature in Docusaurus, and implementing said feature into my own project. The feature I selected was a search function. You can see it running live at https://paulkim26.github.io/til-to-html/.

What does this feature entail?

The feature I implemented was a search field, similar to the one found in Docusaurus. I added an HTML input field that, upon a change in input, will mark text in the generated static site that matches what was entered in the search field (source). It'll allow users to quick find text they are looking for and, in the future, across multiple pages - not just the current page. It works by:

Reading the contents of a TIL post's HTML after it is generated.
Checking for instances of the current keyword entered in the search field via a regex match (not including text encapsulated within the chevrons of HTML tags).
Replacing matched text with a copy encapsulated between HTML <mark> tags.

Why this feature?

Working with new features, frameworks, and tools, the experience of reading documentation is a critical part of it. I have been lucky to work with projects that feature really easy to read documentation such as USWDS and Bun, but I've also had the misfortune to work with pretty terrible documentation like JSDoc. The JSDoc documentation lacks a search field which makes searching for specific items an ordeal and also does not cover many hidden use cases. It provides less than the bare minimum for what it needs to do - a lot of the time I am forced to rely on external user documentation elsewhere to use JSDoc effectively. That was why I was drawn to the search field in particular in Docusaurus.

Comparison to the Docusaurus Search feature

The most important distinction is that it is an offline local search function and not the Algolia DocSearch powered search featured in Docusaurus. I considered implementing Algolia DocSearch in my application but realized that does not make sense in this context since Algolia DocSearch needs to scrape sites to generate its search results. til-to-html is a static site generator for short form posts in similar scope to a blog - it is not "documentation" in the sense that Algolia DocSearch is primarily built for. It would still be nice to be able to search for specific content within til-to-html, but without the extensive overhead and functionality that Algolia provides. I determined an offline solution would be more suited for this context.

Next Steps

This is just the start of the feature. At the moment, the search is limited to the current page - it is no better than the ctrl-f function of any browser. I plan to:

Provide the ability to search between multiple pages
Allow the user to see a list of all search result instances
Allow users to quickly switch between generated pages via a table of contents either within a sidebar or an index page

If you're interested in helping out, take a look at the issues page - the more the merrier!

Issues: https://github.com/paulkim26/til-to-html/issues

Thanks for reading!

Performing a Code Reading of Docusaurus

Paul Kim — Mon, 30 Oct 2023 04:27:51 +0000

For this week in Topics in Open Source Development, I was tasked with performing a code reading of Docusaurus, a popular documentation static site generator.

Docusaurus provides the ability for users to search through documentation. Instead of bootstrapping its own search function, it leverages existing solutions which the developer can choose from, including Algolia DocSearch, Typesense, a variety of community plugins, or one's own search solution. Since Docusaurus does not provide a native search function and relies on third party solutions, this code reading will focus on how it integrates the Algolia Docsearch search functionality into its UI.

Docusaurus Repository: https://github.com/facebook/docusaurus

Documentation

The documentation to configure a search function for one's website is found in website/docs/search.mdx. This same page is hosted officially at https://docusaurus.io/docs/search.

It is a MDX file that combines both markdown and JSX syntax, though it does not use MDX specific syntax. It does however use Front Matter syntax for use with the Front Matter extension, adding a keywords attribute in a front matter block as its header, which defines parseable metadata.

---
keywords:
  - algolia
  - search
---
...

I haven't worked with MDX or Front Matter before, but I've seen (remarkably) similar syntax with Obsidian's Tags syntax. This provides a way to tag and parse otherwise simple markdown files in a powerful, programmatic way.

Docusaurus Classic Preset

Docusaurus features a set of presets - bundles of packages and plugins. Of note, the classic preset supports the Algolia DocSearch by default. It does so by incorporating the theme-search-algolia theme.

export default function preset(
  context: LoadContext,
  opts: Options = {},
): Preset {
  const {siteConfig} = context;
  const {themeConfig} = siteConfig;
  const {algolia} = themeConfig as Partial<ThemeConfig>;
  const isProd = process.env.NODE_ENV === 'production';
  const {
    debug,
    docs,
    blog,
    pages,
    sitemap,
    theme,
    googleAnalytics,
    gtag,
    googleTagManager,
    …rest
  } = opts;

  const themes: PluginConfig[] = [];
  themes.push(makePluginConfig('@docusaurus/theme-classic', theme));
  if (algolia) {
    themes.push(require.resolve('@docusaurus/theme-search-algolia'));
  }
  ...
}

If a configuration object (resolved into the algolia Partial<ThemeConfig>) is not provided when instantiating this preset, the preset will not include the theme-search-algolia theme. This is due to the fact that usage of the Algolia API requires the API variables to be defined in docusaurus.config.js (details here).

Docusaurus Algolia Search Theme

The Algolia search theme package is found in /packages/docusaurus-theme-search-algolia. The package module and its types are defined in the theme-search-algolia.d.ts file. I've seen and used similar instances of declaring types (and their subtypes) in their own dedicated file for visibility.

The docusaurus-theme-search-algolia/src/index.ts file defines the function themeSearchAlgolia which returns the instantiated plugin of type Plugin<void>, which is a type used to define Docusaurus plugins and contains data members such as its name, webpack configuration, file paths, HTML tags to inject, and translation files. Of note, it takes in a themeConfig object which includes the Algolia API configuration data.

In this package's src folder there are the following directories:

__tests__
- Jest tests including:
  - A minimal configuration using a sample Algolia configuration (including a sample Algolia key and Algolia application ID) (link).
  - Passing an unknown key in this configuration (link).
  - If the Algolia configuration object is undefined (link).
  - If the API key is missing (link).
client
- A function to retrieve the theme configuration object (link).
- A function to parse URLs returned from Algolia into local paths that can be navigated to within Docusaurus. This is done by first checking whether it is an external domain with a regex pattern match, then converting it to a relative URL (link).
templates
- Contains an HTML tag to integrate with the OpenSearch API (link).
theme
- The Search Bar React component (link)
  - Returns a custom DocSearch component (link).
  - This component includes a property titled transformSearchClient (link) which calls the addAlgoliaAgent method from the algoliasearch/lite package, which adds a custom user agent to interact with Algolia API (link).
  - This search bar component is meant to be inserted into the navbar component for a theme, such as the Docusarus classic theme's navbar component (link).
  - To "prepare" the browser to load subsequent queries from the Algolia API, a <link> tag referencing the Algolia service (link) is placed in the <Head> component that is not actually rendered to the client and serves no other purpose.
- The Search Page React component (link)
  - A dedicated search page component.
  - An Algolia client is constructed using the appId and apiKey stored in the theme configuration object (link).
  - To use this client in a meaningful way, an Algolia helper is constructed where the parent component can define options including how many results to show per page (link).
    - Upon receiving a search result (link), a callback function is called that sanitizes the returned result and parses the result array via the JavaScript map method, returning an array of objects that includes the title, URL, a textual summary, and a trail of breadcrumbs to follow.
    - The searchResultStateDispatcher method is called with the returned and parsed search results to be stored in state.
  - Renders a dedicated link to www.algolia.com (link).

Code Reading Techniques

To perform this code reading, I opened this project in VS Code which I am more comfortable with instead of using GitHub code search or git grep. The "search all" function was the most useful, as well as "Go To Definition" to see where a function alias was originally defined. I started by searching for the instances of the word search throughout the project to find modules that were relevant to the search function. Next, I observed the file and folder structure to understand how the project was laid out.

Directories of note include:

__tests__
- Tests specific to validating the packages.json and tsconfig.json files.
admin
- Instructions for environment setup, testing, debugging, publishing, and other miscellaneous files.
examples
- Example Docusaurus projects.
packages
- Docusaurus packages including presets, scripts, plugins, types, utility functions, and themes.
website
- The official Docusaurus website to be rendered and hosted. Acts as the single source of truth for Docusaurus documentation.

If there was any code that was unfamiliar to me (such as MDX syntax), I pasted it into ChatGPT to identify the type of syntax I was looking at (if I could not discern it from the filename extension). I also looked through the official Docusaurus documentation on how to implement the search function for more clues.

Thanks for reading!

Hacktoberfest Week 2

Paul Kim — Mon, 16 Oct 2023 00:39:25 +0000

For Topics in Open Source Development, the other students in this course and I are partaking in Hacktoberfest - a month-long open source community event where participants submit 4 pull requests to participating projects.

In this post I will cover my experience finding a second issue to work with and submitting a pull request.

Ordspel

For this entry, I've found a project called Ordspel - a website that features a collection of word games based on IKEA furniture names. You can play them at https://ikeawordgames.com.

Issue

The issue can be found here.

The problem is that in Jumble - one of the word games - the visual keyboard allows players to enter any letter in the alphabet. This causes some friction since players cannot enter any letters outside of the provided ones. You can give Jumble a try here.

The maintainer wanted the non-solution letters to appear disabled/faded out so players wouldn't click on them. Additionally, there should be negative visual feedback from the game if the player were to click on a disabled letter anyway (i.e. the input field shakes).

How it looked before:

How it looked after:

Analyzing the project's code

Looking through the code, I was pleasantly surprised with how straightforward and well organized the project was. Project setup was straightforward; just installed the node dependencies and ran in development mode. Ordspel is a React Next.js web application that uses Chakra UI as its UI component library, which was right up my alley.

The first step was to identify the part of the code that was responsible for handling the visual keyboard. I found that it was a custom React component named WordInput. It acted as a wrapper for a package called simple-keyboard.

My first suggestion (post here) was to implement a disabledKeys property where a parent component can stipulate which keys to specifically disable. avikantz (the maintainer) suggested to use the existing targetValue property to determine which keys to disable, which was fine by me.

Figuring out which keys to disable

The targetValue property represented the target answer string the game was looking for. It was simple enough to figure out that the "bad" keys are just the rest of the keyboard (link). However, since this game is based on Swedish words, there are special diacritics to handle - letters with umlauts i.e. Ö, Ä, Ü. Thankfully, the maintainer already provides a removeAccents() method that strips these umlauts, making using the latin-only simple-keyboard interface easy to work with.

Making changes - look and feel

The next step was to see if simple-keyboard's API provided an easy way to disable specific keys already. Turns out it didn't - should've figured as much. I looked through the documentation to see if there were any options that would be helpful. The buttonAttributes option allowed me to assign a specific attribute to specific keyboard keys which I could target via CSS (link). That handled the "look" of the disabled keys at least.

Making changes - functionality

To make the disabled keys non-interactable I used the inputPattern option provided by simple-keyboard. This allowed me to specify a regex pattern that determined which keys to allow input for - in this case any characters not found in the solution. While this works, it did not allow me to satisfy the maintainer's design requirement to provide negative visual feedback (i.e. a shaking input field) since the input is simply ignored. So I had to look for another solution provided by the keyboard's API. It was a shame that this documentation does not provide a search function - it would have made searching for specific functionality a lot easier.

I realized that the only way to handle this situation was to leverage the existing onKeyPress callback function (link). From there I could check what the current input of the field was and determine whether it contained a character from a disabled key or not. If so, I "jiggle" the input field as negative reinforcement and return early (link). The animation uses the useAnimate function from the Framer Motion animation library.

Afterwards, I created a pull request following the template provided by the maintainer and am now waiting to hear back.

A new issue

While I was working on this project, I noticed there was a pre-existing bug - one could enter additional characters into the input field for Jumble via the visual keyboard. You couldn't see them but they were there - you can backspace to get rid of them. Thankfully I already had a solution in mind.

I posted a new issue and created a pull request - the problem was that the length of the stored "input" of the keyboard component could exceed Jumble's allowed length. The solution was to truncate this value during the onKeyPress callback so that any extra characters were always sliced off (source). While it was possible to limit this field's length in other ways, doing this check during the callback allowed me to provide negative visual feedback (i.e. the same "jiggle").

Takeaways

All in all this was a very fun project to work with. The website was interesting, the project was well organized and documented, it was straightforward to set up, the maintainer was amicable and timely in their responses, and it was fun to use new libraries.

The most difficult part was working around the limitations of the simple-keyboard API. It was tempting to look for workarounds or create a custom fork of this library that gave me more control, but in the end it provided just enough functionality for me to work with to complete my tasks. The lack of a search function in the documentation made the process surprisingly difficult - I hope that all of the documentation I have to deal with in the future provides one.

Thanks for reading!

Hacktoberfest Week 1

Paul Kim — Sun, 15 Oct 2023 13:51:53 +0000

In this post I will cover my experience finding a good issue to work with and submitting my first pull request.

Searching for issues

The first challenge was to find issues that were acceptable to work with. I queried for issues on GitHub with the following filters:

is:open is:issue label:hacktoberfest label:"good first issue" archived:false no:assignee -linked:pr comments:0 created:>2023-01-01

This will filter down issues that are:

Participating in Hacktoberfest
Open and unassigned
Created recently
Marked by the maintainer to be easier to work with

Browsing through various repos, I learned to avoid repos that:

Were inactive/abandoned
Had few to no comments
Were simple student projects
I simply did not understand

I avoided issues that:

Involved adding onto lists of content
Involved localization (I only know English)
Were about providing wireframes/design prototypes
- I presumed that designing (vs. actual coding) was outside the scope of this class
Were about creating their readme
- This signaled to me that the project was unorganized and unmaintained if they relied on external contributors to document their project
Involved refactoring the entire project
- Out of scope

Process

My original plan to contribute was:

Find available issues that are labelled hacktoberfest
Check that I can properly set up the project locally
Respond to the issue and:
- Introduce myself to the maintainer
- Briefly described my propose solution and approach
- Request assignment & permission before starting

Blockers

Within these parameters, I found there was no shortage of interesting projects to worth with. The difficulty came however with certain blockers.

My first blocker was being unable to successfully run certain projects despite following their set up guide. After following the extensive set up guide for a repo, the program would act in an aberrant way that prevented future development i.e. receiving random errors. It would be unclear without further context whether this was an issue during set up, runtime, or if the project was simply broken.

The second blocker were projects with inaccessible pre-requisites. Many projects I've looked into required signing up for an external proprietary service that I was unable to set up.

For example, a project required that I specifically created a developer account in the development platform Deta Space. According to the documentation, this was done by enabling an Enable Developer Mode switch on the sign up page which was not present. Unfortunately, I later realized that the documentation was obsolete and there was an undocumented developer-specific sign-up route https://deta.space/signup?dev_mode=true. Now that I know, I may revisit this project. It's just a shame that the requisite platforms for certain projects may be blockers in and of themselves.

Another blocker was waiting on feedback for proposed improvements prior to starting. Certain issues like this one with this accessibility-focused USWDS React component library have multiple approaches. In this case, the maintainer wondered whether or not a label should be hardcoded into a combo box React component for the sake of enforcing accessibility and that they could be convinced of either approach. I posted my response detailing my approach to this problem. Unfortunately, I did not receive a response. I am not sure whether I should have submitted a pull request anyway, but I would prefer to have some initial feedback before starting one.

Finding the first issue

I found a project called movex - a serverless data sharing infrastructure that allows one to easily develop network-focused apps without worrying about the back end logic. This looked like a great tool to use especially for front-end developers who want to focus on client-facing functionality and aesthetics.

The set up process was straightforward. The project was very well documented, between its contributing guide to its API documentation. The only new requisite I had to prepare was NX to handle building and testing the project.

The issue was simple - to add commitizen to the list of project dependencies. This project uses commitizen to enforce a structure to commits, similar to the Conventional Commits specification which I already know. Up until now, the project relied on contributors to install commitizen globally on their machine (i.e. npm install -g commitizen) before they made commits. This way, everyone was using commitizen from the start.

Submitting my first pull request

After reading through the contribution guidelines and pushing my changes, I noticed that in my pull request I forgot to properly sign my commits - whoops! The fix was easy thankfully - I set up a new gpg key, associated it to my GitHub profile, amended my commit retroactively (making sure to sign it this time), and force pushed it to my feature branch on my fork. The maintainer was fast to respond and pleasant to interact with - certainly a project I look forward to following and potentially to work on further.

Takeaways

The biggest lesson I learned from submitting my first Hacktoberfest pull request and talking with my colleagues was that instead of always waiting for permission from maintainers to publish a pull request, sometimes I should put one out anyway. A pull request can be a great starting point for discussion under some circumstances. The same can't be said for larger, more involved issues that absolutely do require further communication and coordination. The experience of submitting this first issue, while simple, helped me learn the intricacies of contribution, particularly with signed commits.

Another lesson I learned was that it truly is a wild west of projects out there. Aside from the time pressure of racing to contribute to Hacktoberfest-specific issues before they're assigned to someone else, there is a spectrum of quality with these projects. They may feature incomprehensible errors out of the gate, lack proper documentation, are cumbersome to set up, etc. There are also many well-maintained projects out there as well, it just takes some time (and luck) to sift through and find them.

Thanks for reading!

Code refactoring practice

Paul Kim — Sat, 14 Oct 2023 05:53:56 +0000

For this week's lab in Topics in Open Source Development, I was tasked with:

Refactoring my code repository
Using git rebase to alter my commit history
Squashing multiple commits into one
Amending a previous commit
Merging commits

GitHub Repository: til-to-html

Refactoring

With two recent pull requests from external contributors merged in, the code repository was ready for some refactoring. A lot of new features had been added onto my code base from a lot of different people - it was time to clean it all up. Refactoring changes included:

Rethinking how my program handles custom command line arguments
Cleaning up extraneous whitespace and deviations in coding style
Adding missing documentation
Removing extraneous files (i.e. a newly added package-lock.json)
Consolidating redundant functionality into one code

It was satisfying to look at my code again and see new patterns and flows appearing. The act of looking over new features like the --config flag recontextualized my prior code - instead of leaving it in a state where it was "added onto" existing code, I found new ways to "integrate" it.

The previous pull request had added new configuration file parsing functionality to my main index.ts file (source). I moved this new feature into my parseArguments.ts module (source) and consolidated the previously added configuration.ts and configurationParse.ts modules into a single one.

I also cleaned up some inconsistencies with the coding style, including replacing the usage of the var keyword with const or let and reformatting my code with Prettier.

After all of these changes, I tested all of my use cases again to ensure they were all working. There were no bugs before to fix so that was good. I did notice the configuration loading feature handled command line switches like -v and -h - I eliminated support for those since that was out of the domain of .toml configuration files.

Rebasing and amending commits

After making all of my changes in a refactoring branch, I performed an interactive git rebase which allowed me to squash all of my commits into one. Then I used git commit --amend to change the commit message. Then I merged this refactoring branch into the main branch.

Squashing commits definitely helped clean up my git commit history. While I could have simply fast forward merged all of these individual commits into my main branch, it would have polluted my commit history for the future. In the grand scheme of things, I doubt I would need to pick apart and checkout specific commits from this refactoring process down the line.

I typically perform commit squashes and merges on GitHub directly but it was nice to do all of that in a local git environment. That said, I plan to still utilize GitHub's versions of these interfaces when collaborating with others in addition to using git.

Thanks for reading!

Working with Git remotes and merging

Paul Kim — Fri, 06 Oct 2023 05:40:20 +0000

For this week in Topics in Open Source Development at Seneca College, I was tasked with:

Adding a new feature to another student's repository
Practicing working with git fetch and git merge

Finding a new partner

For this lab, instead of working with my previous partner, I was asked to work with someone else for a change. I noticed my buddy Bryce's project ez-txt2html was not yet worked on by anyone else. His version of our tool was written in Python - a language I've only had minimal experience working with. It looked like a great opportunity to work with that language so I decided to post an issue to add this week's new feature.

While I was going through and playing with his code, I noticed it was missing a .gitignore file which made it cumbersome when VS Code kept trying to track some generated HTML files; I opened a separate issue and PR to address that.

Introduction to TOML

Lab 4 asked us to add the ability to load TOML configuration files with pre-defined arguments to each others' projects. I had never heard of TOML, it's pretty neat! It reminded me of YAML and its intent to be a human readable, simple, open-source alternative to JSON that was still widely used. It's pretty interesting how ubiquitous open-sourced standards and conventions can become in the global code space. I only worked with TOML a little bit for this lab and just barely scratched the surface (which I get into below). It looks like a standard .ini file but with fancy new features like keys, values, section headers, but with some interesting caveats like:

A standardized datetime type
Arrays
Objects
Tables

I will definitely look for ways to integrate TOML into my future projects and working with it more.

Implementing the new TOML loading function

I looked over Bryce's code; all of the core functionality was on one .py file so that made things simple to understand. I added a new -c/--config argument to his argparse command line parser. I added a new TOML loading function which leverages the tomllib module. Again, its fantastic that this Python specific implementation of TOML exists and is open source. Best of all, it's natively integrated into Python 3.11 - no fuss, no muss. It's also fantastic that there's not just one implementation - there's also pytomlpp and tomli, pick your poison.

Here's my function:

# Load arguments from a config file
def loadConfig(configPath):
    try:
        with open(configPath, "rb") as f:
            config = tomllib.load(f)
    except FileNotFoundError as e:
        raise Exception(f"Config file '{configPath}' could not be found.")

return config

Pretty simple stuff. I both catch and throw an exception if there's problems with loading the config file. I call this function in the main argument handling function and override the command line argument values.

I add a new sample config.toml file to play with.

output = "./HTML"

This application does not yet implementing more options, so the TOML sample was accordingly simple; just an option to pre-define the output parameter. After testing and making sure it looked okay, I pushed a PR for Bryce.

Feedback

Bryce accepted the PR, but did note that some more documentation would be ideal. I totally forgot to include the implementation details in the README.md, silly me. I added that soon after.

All in all, a fun little feature addition experience.

Working with Git remotes and merging

Note: As of writing, I have not received a pull request for my application til-to-html, sadly.

As this part of the lab is contingent on receiving a pull request from someone else to experiment with, I will update this section when I do.

Thanks for reading! See y'all next week.