DEV Community: Vinh Nhan

Contributing to Open Source: Part 3 - Adopting a New Project and Final Reflections

Vinh Nhan — Wed, 11 Dec 2024 19:36:44 +0000

Hello!! 👋

If you are new here, be sure to check out the first and second blog of this series, where I discuss the planning stages and progress updates of my open source project contributions.

After facing several hurdles with my initial project, Clean and Green Philly, I’ve decided to pivot to another exciting open-source initiative: Le Git Graph. This change was inspired by my friend Peter Wan, and I’m thrilled to document my contributions to this new project.

Project Overview: Le Git Graph

Le Git Graph is a browser extension that adds a "Commits" tab to GitHub’s navigation bar, displaying a colorful commit history graph for any repository. As a developer and visual learner, this tool resonates with me—it provides an intuitive way to track a project’s progress and workflow.

What excites me most is that this is my first time working on a browser extension. It’s a great opportunity to expand my technical skill set and contribute to a tool that enhances the developer experience.

Issue 81: Disappearing Commit Button

Description:
The "Commits" button, added by the extension, disappears after navigating to certain subsections of GitHub (e.g., creating a new issue). To make it reappear, users must refresh the page, disrupting their workflow.

Investigation and Solution

Initial Findings:

The code in main.js, which adds the "Commits" button, executes only on the initial page load.
GitHub operates as a Single Page Application (SPA), so navigating within the site doesn’t trigger a full page reload. This causes the button to disappear as the URL changes.

Proposed Solution:
To ensure the button remains visible and functional, I implemented a solution to dynamically observe URL changes and re-add the button when necessary.

Observing URL Changes:
I used a MutationObserver to detect DOM changes and identify when the URL changes.
Reattaching Click Events:
- The button’s click event wasn’t working after navigation because new events were being added without removing the old ones, causing conflicts.
- I fixed this by removing any existing click events before reattaching them.
Fallback for Missing Elements:
- Certain GitHub tabs, like "Actions" and "Wiki," don’t contain the clearfix element used in the original code.
- I added a fallback using the PageLayout class, ensuring compatibility across all tabs.
Handling Browser Back Button:
- The back button posed a unique challenge. Although the button remained visible, its event listener wasn’t reattached.
- I resolved this by clearing the button’s attributes and events before reinitializing it.

Results and Reflections

Achieving My Goals

Although my original plans with Clean and Green Philly didn’t materialize due to delays and lack of updates, transitioning to Le Git Graph allowed me to stay productive and achieve meaningful contributions. This experience highlights the importance of having a backup project to pivot to when initial plans don’t go as expected. Flexibility and adaptability are critical in open-source work.

With Le Git Graph, I achieved my goal of addressing a significant usability issue and making the extension more robust. My contributions ensure that the "Commits" button behaves consistently across various GitHub tabs and scenarios, providing a smoother user experience.

How I Built the Solution

Technical Features:
- Utilized MutationObserver to monitor DOM changes dynamically.
- Implemented logic to clear existing event listeners and attributes to avoid conflicts when reattaching events.
- Added fallback mechanisms for missing elements to ensure cross-tab compatibility.
- Accounted for browser back button behavior to reinitialize the button seamlessly.
Methods:
- Incremental debugging and testing.
- Researching GitHub’s DOM structure and understanding SPA challenges.
- Iterative improvements to refine the solution.

Here's a demo of my solution:

Check out my pull request here.

Lessons Learned

Technical Growth:
- Working on a browser extension introduced me to tools and concepts I hadn’t used before, such as handling SPAs and dynamic DOM updates.
- Debugging in a live environment required a meticulous approach and patience.
Problem-Solving Approach:
- Breaking down issues into smaller tasks made them manageable and less overwhelming.
- Adapting to unforeseen challenges strengthened my problem-solving skills.
Importance of Backup Plans:
- Having a secondary project ensured I could continue contributing without losing momentum when obstacles arose with the first project.

Leveraging the Community

Engaging with the open-source community was invaluable. I:

Reviewed existing issues and discussions to gain context.
Shared my findings and sought feedback from maintainers and other contributors.
Learned from similar issues and solutions in other projects, broadening my knowledge base.

What’s Next?

Working on Le Git Graph has been a rewarding experience. Moving forward, I plan to:

Continue refining the extension and exploring other open issues.
Leverage this experience to contribute to more browser extension projects.
Share what I’ve learned to inspire others to explore open-source contributions.

This blog also wraps up my series on open source contributions. If you’ve made it this far, thank you! ✌️

Contributing to Open Source: Part 2 - Progress Update

Vinh Nhan — Wed, 11 Dec 2024 18:58:19 +0000

Hello!! 👋

Check out the first blog of this series here.

In the second part of my open source journey, I’ll provide an update on my contributions to Clean and Green Philly. This post covers my progress, challenges, and lessons learned so far.

Issue 1024: Filter Scrolling Bug

Description: When applying a filter, the interface scrolls to the top of the filter list, breaking user concentration. Users should remain in their previous scroll position for a smoother experience.

Investigation and Solution:

After investigating, I found that React’s re-rendering behavior (triggered by state updates) causes the scroll position to reset.
My approach was to save the previous scroll position (scrollTop) when a filter is applied and restore it after the component re-renders.

This solution works but has a minor drawback: the UI briefly scrolls to the top before returning to the saved position, creating a flashy effect. To address this, I’m considering implementing a smoother animation using Framer Motion, as it’s already part of the project’s toolset.

Here's a demo of what my solution looks like:

Current Challenge:
While attempting to commit and push my changes, I encountered a separate issue (Issue 1038) that has blocked my progress.

Issue 1038: Dependency Vulnerability

Description: A cross-spawn vulnerability in the dependency tree prevents code commits. Specifically, the project uses @semantic-release/npm, which has a dependency on an outdated version of npm that includes cross-spawn@7.0.3, a vulnerable package.

Investigation and Solution:

The root cause lies in the package-lock.json file, which locks the vulnerable version of cross-spawn.
My proposed solution is to update all dependencies and regenerate the lockfile. Since manually editing the lockfile is not recommended, I attempted it cautiously, confirming that npm is the only dependency of @semantic-release/npm. This workaround allowed me to resolve the issue locally.

Current Challenge:
I’ve shared my findings and proposed solution with the maintainers, but I’m awaiting feedback to confirm the best course of action before proceeding.

Issue 927: Creating a Stakeholder Outreach Page

Description: External stakeholders need an efficient way to reach out to the team. The proposed solution is a contact page that collects data via a Google Form linked to a Google Sheet. This eliminates the need for a backend.

Progress:

The UX/UI team is working on mockups for the page.
Despite my follow-ups over the past three weeks, I’ve not yet received the final mockups. The most recent update from the team was last weekend (Dec 7-8), but no tangible progress has been shared so far.

Reflections and Lessons Learned

Technical Challenges: Investigating bugs and dependency issues has deepened my understanding of React’s rendering behavior and dependency management.
Collaboration: The delay in receiving mockups underscores the importance of clear communication and realistic timelines when collaborating with cross-functional teams.
Community Interaction: While awaiting responses from maintainers, I’ve realized the value of patience and persistence in open-source contributions.

Despite the hurdles, I’m determined to meet my goals. In the next post, I’ll share how I adapt my approach to overcome these challenges and reflect on the overall experience of contributing to Clean and Green Philly. Stay tuned for Part 3!

Contributing to Open Source: Part 1 - The Planning Stage

Vinh Nhan — Wed, 04 Dec 2024 22:13:38 +0000

Hello!! 👋

As I embark on my journey of contributing to open-source projects, I’m excited to document my experience in this three-part blog series. This first post focuses on choosing a meaningful project, planning my contributions, setting clear goals, and laying out a roadmap for success. I’ll be working with Clean and Green Philly, an initiative dedicated to transforming Philadelphia by greening and cleaning vacant and abandoned parcels—a powerful strategy to reduce gun violence and foster community well-being.

What I Plan to Do

My primary goal for this phase is to address front-end bugs or enhancements in the project. Specifically, I’ll:

Investigate and resolve existing issues: Dive into the GitHub repository to identify front-end problems that require attention.
Work on new feature requests: One notable feature request is creating an outreach/contact us page, which will streamline communication between stakeholders and the project team. This page will make it easier for community members and partners to connect with the initiative.

Why I Am Choosing This Work and Project

I’ve chosen this project because it aligns with my values and offers a meaningful opportunity to contribute to social impact. The work being done by Clean and Green Philly goes beyond technology—it’s about fostering safer neighbourhoods and creating spaces that inspire hope and resilience. Being part of such a transformative initiative motivates me to bring my best effort to this contribution.

How I Will Approach It

Identify opportunities: I’ll regularly check the project’s GitHub repository for open issues, enhancements, or new proposals.
Thorough investigation: For each issue or feature request, I’ll take time to understand the problem deeply by reviewing documentation, code, and stakeholder feedback.
Collaboration: Since the contact us page involves cross-functional teams such as UX/UI designers, I’ll communicate and coordinate with relevant departments, and gather requirements to ensure the final product meets expectations.
Iterative development: I’ll adopt an agile mindset, delivering smaller milestones and gathering feedback throughout the process to refine the work.

What I Hope to Achieve

Through this phase, I aim to:

Enhance my technical skills by working on real-world front-end development challenges.
Develop soft skills such as collaboration and project management by engaging with different teams.
Make a tangible contribution to a project that improves lives and communities in Philadelphia.

By setting clear goals and committing to a structured approach, I’m setting myself up for success. I’m eager to see the positive difference I can make through my work and look forward to the learning experiences along the way.

If you made it this far, thank you! And stay tuned for part 2 and 3! ✌️

Fixing Sorting and Visibility Issues: A Development Diary in Open Source Projects

Vinh Nhan — Fri, 29 Nov 2024 23:49:47 +0000

Hello!! 👋

Freifahren and Impress are two exciting projects I’ve been working on. Recently, I had the opportunity to address two critical issues: sorting station names in the ReportForm for Freifahren and reordering visibility options in the dropdown menu for Impress. Below is a breakdown of the challenges, solutions, and lessons learned along the way.

Freifahren: Fix Sorting Order of Stations in ReportForm

The Problem

In the ReportForm, station names were being sorted alphabetically by their IDs, rather than by their names. This caused confusion, as station names are a more intuitive way for users to locate entries. Issue 300

Challenges Encountered

During the process, I faced a few challenges:

Missing Environment Variables: The RISK_API_URL was required during backend setup, but its purpose wasn’t clearly documented.

After consulting with the maintainer, I learned that the variable is related to a microservice for calculating risk. Since it wasn’t necessary for this task, I could safely ignore it.
Content Moderation Microservice: Submitting a report involved hate speech detection using the CONTENT_MODERATION_SERVICE_URL. Without it, the PostInspector route returned an Internal Server Error.

The maintainer clarified that I could access the service at http://88.99.56.234:9090 or run it locally using the provided documentation.
Misunderstanding the Issue: Initially, I thought the sorting issue was in the ReportsModal, but the maintainer clarified it was actually in the ReportForm.

The Solution

Once I was set up, I implemented the following changes:

Pre-Sorted Stations: The possibleStations list in the ReportForm is now pre-sorted by name using sortedAllStations.
Dynamic Sorting:
- Stations under a selected currentLine are now sorted dynamically from allLines.
- Searches and selections from currentEntity use the pre-sorted sortedAllStations list.

These changes ensure that stations are displayed in a user-friendly order, improving the report submission experience.

The fix was submitted in Pull Request #320.

Impress: Reorder Visibility Options in Dropdown Menu

The Problem

In Impress, the visibility options in a dropdown menu were not ordered logically, which made the selection process unintuitive. Users expected a progression from the most restrictive to the least restrictive option. Issue 397

Proposed Solution

The expected order was:

Restricted
Authenticated
Public

This change was implemented in the LinkReach component, located at src/frontend/apps/impress/src/features/docs/doc-management/types.tsx.

Implementation

By reordering the options in the type definition, the dropdown menu’s display order was updated across the application. This simple change greatly improved the usability of the menu.

The updated logic was submitted in Pull Request #441.

Lessons Learned

Clear Documentation is Crucial:

Having clear, comprehensive, and well-organized documentation can significantly streamline the development process. It helps new contributors quickly get up to speed and reduces the potential for misunderstandings or delays.
Communication is Key:

Regular discussions with project maintainers ensured that I was aligned with the team’s goals and expectations, making the development process smoother.
Small Changes Have a Big Impact:
Fixes like sorting station names and reordering dropdown options may seem minor, but they have a significant effect on user experience and interface intuitiveness.

Conclusion

These updates in both Freifahren and Impress demonstrate how small changes can have a big impact on usability. The process highlighted the importance of clear documentation and effective communication within open-source communities. By addressing these issues, we've made the systems more intuitive and easier to use, paving the way for smoother interactions in the future.

Choosing npm for Release Management

Vinh Nhan — Sat, 23 Nov 2024 04:43:43 +0000

Hello!! 👋

When it came time to choose a release tool and package registry for my project, I opted for npm. Its ubiquity, ease of use, and integration with modern CI/CD workflows made it the ideal choice for my needs.

Creating a Release: Step-by-Step Process

Here’s a detailed breakdown of the steps I took to create a release with npm for my project Barrierless:

1. Set Up an npm Account and Token

First, I created an account on npm. After logging into my account, I generated an npm token from my profile settings. This token is crucial for authenticating with npm during the release process.

I then stored this token in my project’s GitHub repository under Settings > Secrets and variables > Actions > New repository secret, using the key NPM_TOKEN. This ensures that my GitHub Actions workflows can securely access the token without exposing it publicly.

2. Configure a GitHub CD Pipeline

Next, I created a GitHub Actions pipeline file, cd.yml, in the .github/workflows/ directory. This file automates the release process. Here's a simplified example of what the pipeline might look like:

name: CD Pipeline

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
          registry-url: 'https://registry.npmjs.org/'

      - name: Install dependencies
        run: npm install

      - name: Publish to npm
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm publish

3. Prepare the Release

After making updates to my project, I:

Staged and committed my changes:

   git add .
   git commit -m "Prepare for release"

Created a new version tag using npm:

   npm version patch

This automatically updates the version in package.json and creates a corresponding Git tag.

Pushed everything to the remote repository:

   git push origin main --tags

4. Create a GitHub Release

On GitHub, I navigated to Releases, clicked Draft a new release, and selected the tag for the latest version. After providing a description, I published the release. This action triggered the CD pipeline.

5. Verify the Release

Once the pipeline completed successfully, my package was published to npm and ready for users to install.

Lessons Learned

"Aha!" Moment: Missing `NPM_TOKEN`

Initially, my pipeline failed with an error stating that NPM_TOKEN was missing. This was because I hadn’t set up the GitHub secret correctly. Once I added the secret, the pipeline ran smoothly.

Iteration and Debugging

I had to iterate several times to get the process right. Determining the correct order of steps and ensuring all dependencies were properly configured took some trial and error. For example, I forgot to remove extraneous console.log statements from test cases during my first release, which caused confusion during user testing.

User Testing

I asked my buddy, Peter Wan, to test my CLI tool by installing it directly from the npm registry. Initially, he encountered unexpected console.log outputs. After fixing this issue and publishing a new release, Peter successfully tested the updated version.

This exercise reinforced the importance of thorough testing and cleanup before publishing.

Installing and Using the Project

Now that the project is released, users can install it directly from npm. Here’s how:

Install the package globally:

   npm install -g barrierless

Use the CLI tool:

   bl-bot -v

Setting Up a GitHub Actions CI Workflow

Vinh Nhan — Thu, 14 Nov 2024 19:27:42 +0000

Hello!! 👋

When it comes to managing code quality and testing in a collaborative project, setting up Continuous Integration (CI) can be a game changer. GitHub Actions is one of the most popular choices for CI, offering simplicity, flexibility, and direct integration with GitHub repos. Here, I’ll walk you through my experience setting up a CI workflow with GitHub Actions, compare it with my partner’s setup, and share some insights on the challenges and benefits I encountered along the way.

Step-by-Step: My CI Workflow on GitHub Actions

Setting up the CI workflow directly on GitHub was straightforward, thanks to the well-documented interface and ease of YAML configuration. In my setup, I configured the CI to run on every Pull Request or Push to all branches. This means that any code change, whether it's a quick patch or a feature branch, is automatically tested as part of the CI workflow.

My workflow consists of two main jobs:

ESLint - Linting helps catch syntax and formatting errors early, so the code is clean and consistent.
Unit Tests - This job runs all unit tests to make sure that any new changes or additions do not break existing functionality.

Here’s an example of what the YAML configuration for my CI workflow looks like.

In this configuration, GitHub Actions triggers both ESLint and unit test jobs every time there’s a push or a pull request. The eslint job makes sure that code follows our style guidelines, while tests ensures that all tests pass successfully before the code is merged.

How My Partner's CI Workflow Differs

While my setup triggers the CI on all branches, my partner brokoli777's CI, has a different approach. His CI workflow only triggers on the main branch and runs only unit tests. This setup is a bit more selective, ensuring that CI runs only when pushing final code to production. This approach could make sense for certain workflows, as it minimizes the frequency of CI runs, which could save resources and time. However, it also means that potential issues might go undetected on feature branches until they’re merged into the main branch.

Writing Tests for a Partner’s Project

Writing tests for a project I didn’t create had its challenges and rewards. Not being familiar with the full context of my partner’s code required me to spend more time understanding the existing structure and functionality. However, this experience also gave me a new perspective. Testing another person’s code helped me think critically about edge cases and develop a broader sense of good test coverage. It’s a valuable exercise in improving both collaboration skills and the quality of my own code as I apply similar scrutiny to my work.

Reflections on CI with GitHub Actions

Setting up CI has been a highly educational process. Seeing my workflow in action, especially with the ESLint addition (one of the optional challenges), highlighted just how useful CI can be for improving code quality and maintaining consistency across contributions. When I first implemented ESLint, many of my pushes and PRs failed because of minor errors like unused variables. While this was frustrating initially, it underscored the value of having a tool that catches these issues early. By enforcing linting through CI, all contributors are encouraged to follow a unified coding style, making the codebase more cohesive and easier to maintain.

Conclusion: The Value of CI

Implementing a CI workflow with GitHub Actions has been a transformative step in my development process. Not only does it help ensure that all code adheres to quality standards before merging, but it also reduces the potential for human error. From handling new feature branches to enforcing code consistency with ESLint, CI has become an essential part of my workflow, and I look forward to leveraging it even more in future projects.

A Guide to Setting Up Jest for JavaScript Testing with ESM

Vinh Nhan — Tue, 12 Nov 2024 19:48:58 +0000

Hello!! 👋

In this blog, I’ll walk through why I chose Jest as my testing framework, the detailed setup process, handling ESM module challenges, mocking, and environment variable management. By the end of this guide, you’ll have a clear approach to setting up Jest in projects using JavaScript with ESM.

My project repository: Barrierless
Commit for testing: 4b8f1dd

Why Jest?

For JavaScript projects, Jest is a robust testing framework, known for its rich feature set and smooth developer experience. Jest integrates well with JavaScript and Node.js applications, making it easy to write tests with features like automatic mocking and code coverage.

Since Jest is one of the most popular testing frameworks for JavaScript, it has an active community, strong documentation, and compatibility with other popular tools. This support makes Jest an ideal choice for my project.

Setting Up Jest for an ESM-Based Project

Setting up Jest for a project using ECMAScript Modules (ESM) presented some unique challenges. Jest was primarily designed for CommonJS (CJS), so a few additional steps are necessary to make it work smoothly with ESM.

Step 1: Install Jest

To start, install Jest as a development dependency:

npm install --save-dev jest

Step 2: Configure Jest for ESM

Since Jest’s ESM support is still evolving, we need to use a special command to run Jest in ESM mode:

node --experimental-vm-modules node_modules/jest/bin/jest.js

Step 3: Set Up `jest.config.js`

Next, create a jest.config.js file to define Jest’s configuration. This setup cleans up mocks between tests, collects coverage data, and configures environment variables specifically for testing.

Here’s my jest.config.js:

/** @type {import('jest').Config} */
const config = {
  clearMocks: true,
  collectCoverage: true,
  coverageDirectory: "coverage",
  setupFiles: ["<rootDir>/jest.setup.js"], // path to a setup module to configure the testing environment before each test
  transform: {},
  verbose: true,
};

export default config;

Explanation:

clearMocks: Automatically resets all mocks between tests, ensuring a fresh state for each test.
collectCoverage: Enables code coverage tracking.
coverageDirectory: Specifies the output directory for coverage reports.
setupFiles: Loads a setup file before tests, which is useful for setting environment variables.
verbose: Provides detailed test output, helpful for debugging.

Step 4: Set Up Environment Variables for Tests

To avoid using production environment variables in tests, I created a separate env.jest file for testing environment variables. Then, I used dotenv in Jest’s setup file to load these variables.

env.jest (for test environment variables):

   GROQ_API_KEY=
   GEMINI_API_KEY=

jest.setup.js (loads the variables):

   import * as dotenv from "dotenv";
   dotenv.config({ path: "env.jest" });

Handling ESM-Specific Mocking Challenges in Jest

Jest’s documentation primarily covers CommonJS, so ESM-specific details can be a bit sparse. Instead of jest.mock(), ESM uses jest.unstable_mockModule(), which requires a factory function to create mocks.

Example: Mocking a Module in ESM

jest.unstable_mockModule("groq-sdk", () => ({}));

Key Insight: Dynamic Imports for ESM

Since ESM evaluates import statements before other code, static imports load modules before Jest has a chance to apply mocks (read more about it here). To ensure that the mock implementation is applied, dynamically import the module after the mock setup.

jest.unstable_mockModule("groq-sdk", () => ({
  ...
}));

const { Groq } = await import("groq-sdk"); // using await to dynamically import the module

Mocking a Class Using Jest (ESM)

In my project, I needed to mock the Groq class from the groq-sdk module. Here’s how I created a mock that accepts an API key object and checks the validity of it:

jest.unstable_mockModule("groq-sdk", () => ({
  // we put the class's constructor implementation inside the factory function
  Groq: jest.fn().mockImplementation((apiKeyObj) => {
    if (apiKeyObj.apiKey === MOCKED_GROQ_API_KEY) {
      return {
        chat: {
          completions: {
            create: mockCreate,
          },
        },
      };
    } else {
      throw new Error("401: Unauthorized. Invalid API key.");
    }
  }),
}));

Here’s an example of how I tested the Groq class with Jest and ESM.

My original source code creates a Groq instance by passing the API key from an environment variable:

import { Groq } from "groq-sdk";
import * as dotenv from "dotenv";
dotenv.config(); 
import process from "node:process";

const GROQ_API_KEY = process.env.GROQ_API_KEY;

export async function getGroqChatCompletion(
  fileContent,
  targetLang,
  providerModel,
) {
...
const groq = new Groq({ apiKey: GROQ_API_KEY });
...
}

In a test, a Groq object can be instantiated using the mocked Groq class above, like how it would be done realistically. For instance:

test("GROQ API key is invalid, throw error", async () => {
  try {
    const groq = new Groq({ apiKey: "dummy_key" });
  } catch (error) {
    expect(error.message).toMatch(
      "401: Unauthorized. Invalid API key.",
    );
  }
});

Handling Environment Variables in Jest

To work with environment variables dynamically during tests, I adjusted them before each test and imported the testing module afterward. This approach lets the module reference the updated variable, rather than the original value from env.jest.

import process from "node:process";
const originalEnv = process.env;

const MOCKED_GROQ_API_KEY = "123";

describe("getGroqChatCompletion() tests", () => {
  beforeEach(() => {
    jest.resetModules(); // clears the cache
    process.env = { ...originalEnv };
  });

  afterAll(() => {
    process.env = originalEnv; // ensure original values are restored after all tests
  });

  test("valid arguments, return translated content", async () => {
    process.env = { ...originalEnv, GROQ_API_KEY: MOCKED_GROQ_API_KEY }; // set new value to GROQ_API_KEY

    const { getGroqChatCompletion } = await import("../../src/ai/groq_ai.js"); // import the testing module that uses the new GROQ_API_KEY

    const content = await getGroqChatCompletion("Hello", "english", MODEL); // "123" is used here, as opposed to the value from env.jest
    expect(content).toBe("Mocked response: Hello");
  });
});

Mocking Array Modules

For some modules, such as iso-639-3, I had to mock the module as an array to simulate its actual structure.

Source code utils.js:

import * as lang6393 from "iso-639-3";

export function getIso639LanguageCode(language) {
  // ....
  const language6393 = lang6393.iso6393.find(
    (lang) => lang.name.toLowerCase() === language.toLowerCase(),
  );
  // ...
}

My first attempt of mocking iso6393 was:

// wrong implementation
const mockFind = jest.fn().mockImplementation(() => {});

jest.unstable_mockModule("iso-639-3", () => ({
  find: mockFind;
}));

const { iso6393 } = await import("iso-639-3");
const { getIso639LanguageCode } = await import("./utils.js");

However, this would not not work, with the error:

TypeError: lang6393.iso6393.find is not a function

To understand the module, I referred to the source code of iso-639-3 (under node_modules/iso-639-3/iso6393.js), and learned that iso6393 is an array of objects. Therefore, the modified mock implementation is:

jest.unstable_mockModule("iso-639-3", () => ({
  __esModule: true,
  iso6393: [
    {
      name: "Zulu",
      type: "living",
      scope: "individual",
      iso6393: "aaa",
    },
  ],
}));

With the iso6393 array mocked properly, the find() method can be called on ios6393. I could then test functions that depend on this module.

test("language is not found from ISO 639-1, return ISO 639-3 language code", async () => {
  const language = "Zulu";
  expect(getIso639LanguageCode(language)).toBe("aaa");
});

Lessons Learned

Understanding Module Structures: Knowing the actual structure of each module greatly simplifies the mocking process. For instance, iso-639-3 is an array of objects, which I initially tried to mock incorrectly. Looking at the module’s source helped me identify the correct format.
Dynamically Importing Modules: In ESM, dynamic imports after mock setup ensure that Jest’s mocks apply correctly.
Testing with Environment Variables: It’s essential to reset environment variables and cache between tests to ensure consistent results.

Reflections on Testing with Jest

Testing with Jest for ESM projects is challenging, especially due to limited support and extra steps for module mocking and import management. But testing reveals valuable insights, highlights bugs, and forces logical refinements. Now that I’ve worked with Jest’s more advanced features, I look forward to implementing it more in future projects.

With this guide, I hope you can set up Jest effectively for ESM-based JavaScript projects, streamline your testing process, and handle challenges with module mocking and environment management. Testing with Jest is invaluable for ensuring code quality and stability, and the skills you gain here will benefit all your future development efforts.

Adding Static Analysis Tools to the Barrierless Project

Vinh Nhan — Fri, 01 Nov 2024 23:54:41 +0000

Hello!! 👋

As I continue to improve the Barrierless project, I recognized the need to enhance code quality and ensure consistency across all contributions. Adding a source code formatter and linter would enforce a uniform style and prevent common errors, streamlining the development process and making it more efficient for all contributors. Here’s a breakdown of my process and the decisions I made to add Prettier and ESLint to the project.

(Check out the commit for this update here).

Create a `CONTRIBUTING.md` File

To make the development process more accessible for contributors, I generated a CONTRIBUTING.md file using CONTRIBUTING.md Generator. This document provides guidance for contributors on setting up the development environment, coding standards, and submitting changes. By having clear contribution guidelines, I hope to create a more organized and structured experience for future contributors.

Choose a Source Code Formatter – Prettier

Since Barrierless is primarily built in JavaScript, I decided to use Prettier as the project’s source code formatter. Prettier is a popular choice in the JavaScript community, known for enforcing a consistent code style automatically. With Prettier, formatting rules are predefined and eliminate the need for contributors to focus on stylistic details, allowing them to focus on the code logic itself.

To add Prettier, I installed it as a dev dependency and configured a .prettierrc file in the project. This file allows us to customize formatting rules and keep them consistent across the project. I also added a .prettierignore to avoid formatting unnecessary files. Then, I created a format script in package.json to make it easy for contributors to run Prettier with a single command.

Choose a Linter – ESLint

To catch common coding issues and enforce best practices, I chose ESLint as the linter for the Barrierless project. ESLint is highly configurable, and it integrates well with JavaScript projects, identifying potential errors, bad practices, and non-standard code.

After installing ESLint as a dev dependency, I created a lint script in package.json so that contributors can easily run ESLint from the command line.

Fix Errors and Inconsistencies

With these scripts in place, contributors can now use npm run format to format their code and npm run lint to check for any linting issues before submitting a pull request.

After running Prettier and ESLint on the project for the first time, I was surprised by the number of inconsistencies and potential issues they flagged. Many of these were minor syntax and formatting issues, but there were also errors that could have easily gone unnoticed without these tools. Addressing these issues not only improved the code’s readability but also helped to catch small mistakes that could have caused bugs.

Integrate Formatting and Linting with Editor Configuration

To make it easier for contributors to integrate Prettier and ESLint with their editor, I added configuration files under the .vscode folder. These configurations ensure that code is formatted and linted automatically in editors like VS Code, making the development experience seamless and consistent.

Here’s an example of the .vscode/settings.json file configuration:

{
  "editor.insertSpaces": true,
  "editor.tabSize": 2,
  "editor.detectIndentation": false,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit"
  },
  "files.eol": "\n",
  "files.insertFinalNewline": true
}

With these settings, VS Code will automatically format and lint code upon saving, minimizing the manual steps required by contributors.

Document Instructions in `CONTRIBUTING.md`

Finally, I documented all the setup and usage instructions for Prettier and ESLint in the CONTRIBUTING.md file. This documentation explains how to run the scripts, and configure the editor to integrate with these tools. By including these details in CONTRIBUTING.md, I hope to make it straightforward for contributors to follow the same standards without hassle.

Summary

Adding Prettier and ESLint to the Barrierless project was a valuable step in improving code quality and consistency. These tools not only help maintain a uniform code style but also prevent potential issues, creating a smoother development experience for both current and future contributors. I’m excited to see the impact this has on our collaborative efforts, and I encourage anyone interested to check out the project and contribute!

Hacktoberfest 2024 - Last Week + Final Thoughts: Resolving Mobile Navigation Overflow Issues for Clean and Green Philly

Vinh Nhan — Wed, 30 Oct 2024 03:10:15 +0000

Hello!! 👋

In the last week of Hacktoberfest, I tackled an issue with the mobile navigation dropdown for the Clean and Green Philly project. This project, developed to support sustainable interventions to reduce gun violence in Philadelphia, had a minor yet significant problem on mobile devices: the Donate option in the dropdown menu was not fully visible when the screen width was reduced, making it difficult to access.

Issue #976: Donate Option Hidden in Mobile Nav

Bug Overview:

When users navigate on smaller screens, the navigation bar switches to a hamburger menu. The “Donate” option, located at the bottom of this dropdown, was barely visible and difficult to click without scrolling due to the dropdown’s limited height. (Issue #976)

Solution: PR #985 – Adjusting the Mobile Navigation Dropdown `max-height`

My solution was to increase the max-height of the mobile dropdown menu to make sure all items were visible without the need to scroll. This adjustment allows users to access the "Donate" option with ease, improving the accessibility and user experience on mobile devices. (PR #985)

Technical Challenges Faced:

Understanding the Codebase: Being new to the project, I first had to get familiar with its layout and structure.
Styling Libraries: The project uses Next-UI and Tailwind CSS, which were both new to me. I had to quickly get up to speed with Tailwind’s styling conventions to locate and fix the dropdown’s CSS properties.
Locating the Issue: After investigation, I found that the .mobileIconLinkNav class in global.css controlled the height. This class was custom-designed for the mobile nav, and increasing its max-height resolved the issue.
Following Contribution Guidelines: I initially submitted my PR to the main branch, overlooking the instruction to submit to the staging branch. The reviewer helped guide me in switching the PR to the correct branch, emphasizing the importance of following contribution protocols.

Closing Thoughts

This week was a rewarding learning experience that taught me how to quickly adapt to new styling frameworks while making meaningful contributions to a live project. Overall, it was another productive week of Hacktoberfest, and I look forward to tackling more challenges like this in the future!

Hacktoberfest 2024 Wrap-Up

After four weeks of Hacktoberfest, I’m wrapping up with a mix of accomplishment and growth. Each project and pull request has been an opportunity to learn new tools, dive into unfamiliar codebases, and apply my problem-solving skills to real-world issues. Along the way, I’ve expanded my understanding of diverse tech stacks—from navigating Tailwind and Next-UI in Clean and Green Philly to handling GitHub API limitations and exploring effective UI handling techniques.

Hacktoberfest has been more than just about completing PRs; it’s been a hands-on journey into open source collaboration. I’ve gained valuable insights into the importance of clear communication, thorough documentation, and the small but impactful improvements that make a difference in the user experience. Working with different teams has also reminded me how supportive the open-source community can be, with reviewers and maintainers offering constructive feedback and guidance.

Looking back, each week presented new challenges, but each contribution left me more confident in my skills. Hacktoberfest 2024 has not only strengthened my technical abilities but has also reinforced my passion for contributing to projects that create meaningful change. I’m excited to carry this momentum forward, knowing that the experiences I’ve gained this month will benefit future collaborations and contributions. Here’s to many more Hacktoberfests to come!

Hacktoberfest 2024 - Week 3: Fixing Document Title Updates in Impress

Vinh Nhan — Sun, 27 Oct 2024 15:01:57 +0000

Hello!! 👋

This week, I contributed to Impress, a document-editing app, where I worked on a bug related to how users interact with placeholder text in the title field (Issue #328). Here’s a breakdown of the intended functionality, the specific issue, and the steps I took to resolve it.

Expected Behavior

In Impress, the document title field has specific styling to guide users. When the title text is grey, it serves as a placeholder ("Untitled Document"). Once the user edits the title, it should turn black, indicating the update has been successfully saved. The expected behavior is:

Clicking on the placeholder text should activate the text box for editing.
If the title remains unedited, the grey placeholder should persist.
If the title is edited, the new text should display in black.

Actual Behavior

While the title update generally worked, a bug appeared when users selected and edited the placeholder text in certain ways. If users highlighted the placeholder text by double-clicking or dragged the mouse outside the text box area, they could end up modifying the placeholder text instead of starting with a blank title.

In these scenarios:

The placeholder text could be altered while still appearing grey.
After confirming the edit (e.g., by clicking elsewhere or pressing Enter), a success notification would appear, yet the title remained grey, as if it were still the default placeholder, instead of becoming black.

Problem Analysis

In Impress’s DocTitle.tsx, I discovered that handleTitleSubmit was not correctly updating the titleDisplay state when users edited the placeholder text. As a result, the isUntitled flag remained true, keeping the title styled in grey even after an edit.

Solution

To fix this, I modified handleTitleSubmit to ensure it updated both updateDoc with the new title and titleDisplay with the edited value. This change updated the isUntitled flag to false, allowing the title to display in black once edited, providing the user with immediate visual confirmation.

With this approach, the title now correctly turns black after any edits, enhancing the user experience by signaling that their updates have been successfully applied (PR #370).

Challenges

This task presented several challenges:

Code Familiarity: A significant amount of time went into understanding the codebase and setting up the project’s frontend and backend for local development. Grasping the relationships between different components was key to diagnosing the issue effectively.
Exploring Alternatives: My initial solution focused on preventing interactions like double-clicking or dragging on the placeholder text. However, this approach introduced additional bugs and felt like a "band-aid" solution. Refocusing on handleTitleSubmit led to a more sustainable fix.
Pull Request Requirements: During the pull request process, several CI tests failed:
- A CHANGELOG.md entry was required to document the fix, but this wasn’t mentioned in CONTRIBUTING.md, so I initially missed it.
- My commit message format didn’t align with the project’s CI standards.

I addressed these issues in a subsequent commit by adding the required change log entry and reformatting my commit message to match the guidelines.

Reflections

Working on Impress has been a rewarding experience, reinforcing the value of thorough code understanding and the impact of thoughtful, comprehensive solutions. Hacktoberfest continues to be a fantastic opportunity for growth, and I look forward to more contributions this month!

Hacktoberfest 2024 - Week 2: Fixing Makefile Errors in Mikochi

Vinh Nhan — Sun, 13 Oct 2024 21:40:00 +0000

Hello! 👋

Following my successful contribution in the first week of Hacktoberfest , I was eager to continue my journey into open-source development. This week, I focused on the Mikochi project, addressing issue #21 related to errors in the Makefile.

The Issue at Hand

While working on the project, I attempted to launch the development environment using the command make dev, only to be met with the following error:

ls backend | grep __debug_bin | gxargs -I {} rm backend/{}
/bin/sh: gxargs: command not found
make: *** [down] Error 127

The issue stemmed from a minor typo in the Makefile: the command gxargs was incorrectly used instead of xargs. Although it seemed like a small mistake, it significantly disrupted the workflow.

Preparing for the Fix

To resolve the issue, I needed to dive into the Makefile to understand its structure and how the commands were executed. Familiarizing myself with this file was essential for implementing the fix correctly.

The Code Fix

The specific line that required modification was as follows:

Before:

ls backend | grep __debug_bin | gxargs -I {} rm backend/{}

After:

ls backend | grep __debug_bin | xargs -I {} rm backend/{}

By simply replacing gxargs with xargs, I ensured that the command would execute properly without throwing an error.

Challenges and Research

One challenge I faced was distinguishing between standard and non-standard command-line tools. To prepare for the fix, I researched how xargs works and its intended purpose, which helped clarify the root of the issue.

Interaction with Project Maintainers

After submitting my pull request, which you can view here, I had a constructive interaction with the project maintainers. They informed me that gxargs was a non-standard executable that was being used. However, they agreed that using xargs would provide a more universally compatible solution, leading to the approval of my pull request.

Conclusion

This second week of Hacktoberfest has deepened my understanding of open-source contributions and the importance of clear communication with project maintainers. Each issue I tackle not only enhances my technical skills but also builds connections within the developer community. I encourage anyone considering participation in Hacktoberfest to take the leap—you'll gain invaluable experience and make meaningful contributions!

Refactor: How I Improve My Barrierless Project

Vinh Nhan — Sat, 12 Oct 2024 05:43:44 +0000

Hello! 👋

After reading through the refactoring walk-through example in class, it was time to apply those lessons to my own project: Barrierless. The goal was to improve the code’s structure, readability, modularity, and maintainability. Refactoring helps set the stage for long-term success by making code easier to read, debug, and expand, especially with automated testing on the horizon. Here’s how my refactoring journey went.

Step 1: Branching Out

The first step was creating a dedicated refactoring branch from my main branch:

git checkout -b refactoring

This ensured that any mistakes I made during the refactoring process wouldn’t affect the stability of my main branch.

Step 2: Finding the Issues

I reviewed my code and identified three key areas that needed improvement:

Separate Concerns: Modularizing My Code Initially, my code handled command-line arguments, file parsing, AI management, and output all in the same space in index.js, making it harder to manage. I decided to separate these responsibilities into different modules:

One module for command-line arguments and options: /src/cli.
Two modules for input and output file handling: /src/input& /src/output.
A separate one for AI translation management /src/translation.

This refactoring increased the modularity and maintainability of the code, allowing each part to be more focused and reusable. At the same time, I also added a logic to validate the language option specified by the user, based on the IOS639-1 and 3 standard. Then, I created the first commit for this refactor after testing the separation:

   git commit -m "modularize code into input, output, translation, cli. Add IOS639-1 and 3 language standard validation"

Eliminate Global Variables I noticed that some global variables were used in index.js, which could lead to unexpected behavior as the project scales. To fix this, I encapsulated the necessary variables within the respective modules, ensuring that no global variables were needed in index.js. This enhanced the code's reliability and reduced the risk of bugs in that specific file:

   git commit -m "remove global variables in index.js"

Switching from require to import Since I'm working in a modern JavaScript environment with ES6 modules, I replaced require statements with import statements for os and fs in src/utils.js. This not only makes the code more modern but also aligns it with the rest of the current code and the latest JavaScript standards:

   git commit -m "changed 'require' to 'import' for os and fs"

Step 3: Commit and Test

After each refactor, I made sure to thoroughly test the code to ensure I hadn’t introduced any breaking changes. My workflow looked like this:

Refactor a section of the code.
Test the functionality manually.
Commit the changes.

I was careful to follow the rule of one problem, one commit, which kept each commit focused and easy to follow.

Step 4: Interactive Git Rebase

Once I was happy with the refactoring, I performed an interactive rebase to squash all of the refactoring commits into a single commit. This makes the history cleaner and easier to understand. The process was straightforward:

git rebase -i

I marked the commits I wanted to squash, and when everything was ready, I used an amended commit message to add the bullet points to the current commit messages:

git commit --amend

Step 5: Merging the Refactor Branch

With the rebase completed and all tests passing, I merged the refactor branch back into main:

git checkout main
git merge --ff-only refactoring

Finally, I pushed the updated main branch to GitHub:

git push origin main

Lessons Learned

Interactive Rebase: This was a great tool to clean up my commit history. It was my first time using it for squashing commits, and it made the refactoring process feel polished.
Modularization: Breaking up the responsibilities into separate modules made the code easier to read and reason about. It also made debugging and testing more focused.
No Global Variables: By removing global variables, the code is less prone to hard-to-find bugs and is better organized.
Switching to ES6 Imports: This step brought my project up to modern standards, ensuring better compatibility with future projects.

I didn’t encounter any significant bugs during the refactor, but I did notice that some parts of my code were more fragile than I had realized. Refactoring exposed those areas, making it easier to address them in the future. The overall process was smooth, and the improved organization will make future changes easier to implement.

DEV Community: Vinh Nhan

Contributing to Open Source: Part 3 - Adopting a New Project and Final Reflections

Project Overview: Le Git Graph

Issue 81: Disappearing Commit Button

Investigation and Solution

Results and Reflections

Achieving My Goals

How I Built the Solution

Lessons Learned

Leveraging the Community

What’s Next?

Contributing to Open Source: Part 2 - Progress Update

Issue 1024: Filter Scrolling Bug

Issue 1038: Dependency Vulnerability

Issue 927: Creating a Stakeholder Outreach Page

Reflections and Lessons Learned

Contributing to Open Source: Part 1 - The Planning Stage

What I Plan to Do

Why I Am Choosing This Work and Project

How I Will Approach It

What I Hope to Achieve

Fixing Sorting and Visibility Issues: A Development Diary in Open Source Projects

Freifahren: Fix Sorting Order of Stations in ReportForm

The Problem

Challenges Encountered

The Solution

Impress: Reorder Visibility Options in Dropdown Menu

The Problem

Proposed Solution

Implementation

Lessons Learned

Conclusion

Choosing npm for Release Management

Creating a Release: Step-by-Step Process

1. Set Up an npm Account and Token

2. Configure a GitHub CD Pipeline

3. Prepare the Release

4. Create a GitHub Release

5. Verify the Release

Lessons Learned

"Aha!" Moment: Missing NPM_TOKEN

Iteration and Debugging

User Testing

Installing and Using the Project

Setting Up a GitHub Actions CI Workflow

Step-by-Step: My CI Workflow on GitHub Actions

How My Partner's CI Workflow Differs

Writing Tests for a Partner’s Project

Reflections on CI with GitHub Actions

Conclusion: The Value of CI

A Guide to Setting Up Jest for JavaScript Testing with ESM

Why Jest?

Setting Up Jest for an ESM-Based Project

Step 1: Install Jest

Step 2: Configure Jest for ESM

Step 3: Set Up jest.config.js

Step 4: Set Up Environment Variables for Tests

Handling ESM-Specific Mocking Challenges in Jest

Example: Mocking a Module in ESM

Key Insight: Dynamic Imports for ESM

Mocking a Class Using Jest (ESM)

Handling Environment Variables in Jest

Mocking Array Modules

Lessons Learned

Reflections on Testing with Jest

Adding Static Analysis Tools to the Barrierless Project

Create a CONTRIBUTING.md File

Choose a Source Code Formatter – Prettier

Choose a Linter – ESLint

Fix Errors and Inconsistencies

Integrate Formatting and Linting with Editor Configuration

Document Instructions in CONTRIBUTING.md

Summary

Hacktoberfest 2024 - Last Week + Final Thoughts: Resolving Mobile Navigation Overflow Issues for Clean and Green Philly

Issue #976: Donate Option Hidden in Mobile Nav

Solution: PR #985 – Adjusting the Mobile Navigation Dropdown max-height

Closing Thoughts

Hacktoberfest 2024 Wrap-Up

Hacktoberfest 2024 - Week 3: Fixing Document Title Updates in Impress

Expected Behavior

"Aha!" Moment: Missing `NPM_TOKEN`

Step 3: Set Up `jest.config.js`

Create a `CONTRIBUTING.md` File

Document Instructions in `CONTRIBUTING.md`

Solution: PR #985 – Adjusting the Mobile Navigation Dropdown `max-height`