DEV Community: Dharam Ghevariya

My Experience Creating CI Workflows and Contributing Tests to an Existing Project

Dharam Ghevariya — Fri, 14 Nov 2025 18:41:57 +0000

This week, I focused on setting up a complete GitHub Actions CI workflow and writing tests for a codebase I did not originally create. Both tasks helped me understand code quality, consistency, and the importance of automated testing in a project.

To begin with, I created a ci.yml file that runs on push and pull request to the main branch. The workflow has two major jobs. The first is the test job, which runs on a matrix of Ubuntu, Windows, and macOS to ensure cross-platform reliability. It checks out the repository, sets up Python 3.12 with pip caching, installs all necessary dependencies, runs linting and formatting checks using ruff, performs type checking with mypy(static type checker for Python), and finally executes the full test suite with coverage reporting. The second job is a build job that runs only if the tests pass successfully. It installs the build tools, creates distribution packages using python -m build, and uploads the generated artifacts so they can be reviewed.

To test these workflow, I had created a new PR for more test implementation to my project similarly how I discussed in my previous blog. When created the PR it ran the jobs defined the workflow and ran successfully - you can see by visiting GitHub-Action. Along with that I ran once again before merging this PR to main branch: GitHub-Action. To test the failure, I added a bug in test making the job fail - GitHub-Action, and when committing this changes to main branch it shows a red cross(❌) beside the commit message denoting the failure.

One challenge I ran into involved dependency installation. The project uses PEP 735 dependency groups rather than the older optional-dependencies format. Because of this, the usual pip install -e ".[dev]" command did not work as expected. I had to explicitly install individual development dependencies such as ruff, mypy, pytest, and pytest-cov. This gave me a much better understanding of how dependency standards are evolving and how CI workflows need to adapt.

Writing tests for someone else’s project turned out to be a very insightful experience. Since I was not familiar with the codebase, I started by studying the existing tests. The maintainers followed a simple, consistent style where tests were small, function-based, and relied on minimal setup. They used the built-in tmp_path fixture for file handling and avoided heavy mocking. This made it easier for me to understand their approach and write tests that fit naturally into the project. I focused on two isolated utility functions, log_verbose and human_readable_age, which were good candidates for unit testing. Understanding how verbose logging and time formatting worked required some investigation, and GitHub Copilot was helpful in guiding me through the patterns and suggesting test structures that aligned with the existing style. This is the PR I had raised for it: Test/cli functions

Working through this process also changed how I think about continuous integration. With CI running tests, linting, formatting checks, and type checking automatically on different operating systems, I felt much more confident that my code worked properly everywhere. I no longer had to remember to run all the commands myself because the CI pipeline handled everything for me. It acted like a safety net that quickly showed me if something was wrong. Overall, CI made the whole testing process easier, more reliable, and helped me trust the changes I was making.

Building Test Suite for "repo-contextr" using "pytest"

Dharam Ghevariya — Fri, 07 Nov 2025 20:03:34 +0000

When building software, testing often gets pushed to the end (or forgotten completely!). But for my project repo-contextr, I decided to do testing properly from the start. This post shares my experience writing tests and usage of the tool throughout the development process. If you are reading my blog for the first time, please visit my previous posts for a better understanding of the repo-contextr CLI tool.

As this tool was built using Python, I looked for industry standard frameworks for testing within the Python ecosystem. After spending some time comparing different libraries, I selected pytest. This testing framework is straightforward to use, offers a rich feature set, and is widely adopted by the Python community.

Along with the testing framework, I also integrated pytest-cov to measure how much of my code is actually executed by tests. Running pytest alone only tells you whether tests passed or failed, but it does not reveal how much of the logic those tests are exercising. pytest-cov provides a coverage report with detailed visibility into which modules, functions and even specific lines are executed during testing. The coverage insights were especially useful, and additional command examples for usage can be found in the project documentation.

Later, I explored the concept of pytest Fixtures. These allow the reusable creation of setup environments and test data in a clean manner. Instead of repeating the same setup code inside every test, a fixture defines setup once and then makes it available across multiple tests. This improves readability and consistency. If you want to see how fixtures are used in this project, you can refer to the conftest.py file in the test directory.

Setting Up Tests

For test organization, I created a dedicated tests folder separate from the main src code, with conftest.py containing shared fixtures and unit tests stored inside a unit subfolder. This structure keeps test logic isolated from production code and is a pattern many production Python projects follow.

To configure pytest to work the way I expected, I added configuration settings inside pyproject.toml. These settings define where tests are located, how pytest should discover them, and enable strict configuration behaviour. For coverage, I configured coverage to scan only the src directory, ignore test directories and cache folders, and also enabled branch coverage. I generated HTML coverage output through the htmlcov folder, which visually highlighted which lines and branches were tested.

Fixtures in conftest.py helped significantly in avoiding duplicate setup steps. For example, I created a temp_dir fixture to produce a temporary folder for each test. Another fixture, mock_files_dir, automatically placed a small collection of different file types inside the temporary directory. These reusable fixtures improved the clarity of tests, reduced duplication and made the suite easier to maintain over time. The testing documentation inside the repo explains this structure in further detail.

What I Learned

While writing tests, I realized it is not enough to only test normal cases. Empty strings, Unicode content, unexpected edge cases and unusual inputs can reveal subtle bugs, so I made sure to test those early. Coverage reports showed that many untested lines were inside exception handling blocks. After adding tests that simulated permission errors and I/O failures (using unittest.mock), overall coverage increased and the tool became more reliable. This experience reinforced the idea that testing is not only about verifying successful behaviour but also ensuring that failure paths behave safely.

Useful Testing Features

During the process, I discovered several practical pytest options that made the workflow faster. Being able to run just a single test file, a single test class, or even a specific test function helped a lot while iterating and debugging. Coverage visualisation was another valuable tool. Seeing which parts of the code were marked in red encouraged me to target those sections with improved test coverage. The HTML report was especially helpful because it presented code with colour indicators highlighting tested, partially tested and untested lines.

For debugging, pytest allowed me to display variable values at the moment of failure, drop into an interactive debugger and reveal printed output during execution. These features helped make the debugging loop shorter and more interactive.

To keep everything structured, I grouped related test functions into classes. This kept similar tests together, provided a natural grouping for running specific sections of the test suite, and helped improve discoverability. After completing my tests, the total coverage of the project was around ninety five percent, which I find ideal for this stage. The remaining areas that are not covered mostly relate to small display-oriented functions, print messages and type checking logic. These do not directly affect core behaviour and are validated in other ways.

Important Lessons

One of the biggest takeaways from this experience is that writing good tests is not about achieving one hundred percent coverage. The goal should be to achieve the right coverage. I started with basic tests, then gradually expanded into unusual input cases such as empty strings, Unicode content, extremely long inputs and invalid file scenarios. I made sure to test error paths and exceptional behaviour, since those were the most frequently missed lines in coverage reports. Reusing fixtures greatly reduced duplicated setup code, resulting in cleaner and more maintainable test files. Clear and descriptive test names also helped a lot because they communicate exactly what behaviour is being verified, which benefits both future contributors and my future self.

Tackling Bigger Challenges and Exploring New Repositories in Hacktoberfest

Dharam Ghevariya — Fri, 31 Oct 2025 17:20:09 +0000

I’m glad to continue sharing my open-source journey through this third update of Hacktoberfest! In my previous blog, I talked about my earlier pull requests in the Cloudinary community projects, how my fixes got merged, and what I learned from the feedback process. This week brought a few more interesting developments, deeper technical challenges, review discussions, and contributing to different repository.

Continuing the Work with Cloudinary

As discussed in my last post, I had worked on Issue #232 and created a corresponding Pull Request #241.

This issue was about the generative fill feature failing for images larger than 25 megapixels. I fixed the problem by first transforming such large images down to the required pixel limit before applying any other transformations. This approach solved the immediate bug, the plugin no longer failed, but as I later discovered from the review comment, it also had an unintended side effect.

The reviewer explained that while my fix worked for the fill-background plugin, the same issue could appear in other plugins that use Cloudinary’s AI-based features such as gen_restore, gen_remove, gen_recolor, and gen_replace. In short, there was a deeper architectural issue, and my fix needed to be more generic.

Since I’m still new to this project, I didn’t want to rush into implementing a wide-ranging solution without proper guidance. I replied to the comment asking for direction on how to handle this in a scalable way. For now, I’m waiting for feedback from the maintainers before moving forward. It’s a great reminder that sometimes, fixing one bug can uncover a much bigger design consideration and that collaboration is key to solving it right.

Follow-Up Issue and Easy PR

The next related task came from the Next-Cloudinary repository — Issue #592.

As you can see in this comment, the maintainer asked me to upgrade the dependencies to reflect the fixes I had worked on in cloudinary-util.

So, I created PR #636, which simply upgraded the @cloudinary-util/url-loader and @cloudinary-util/util packages in the project’s package.json and reinstalled them using pnpm install. It was a straightforward change, but it ensured the latest bug fixes were included in the Next-Cloudinary SDK. Sometimes, even small updates like this help keep the ecosystem consistent and reliable.

Exploring a New Repository – OpsiMate 💡

After finishing my work on the Cloudinary repositories, I decided to explore another open-source project to broaden my learning experience. That’s when I came across OpsiMate, an open-source platform that helps organizations manage operations, providers, and facilities efficiently. It’s built using a modern stack of TypeScript, Express, and React, which gave me a chance to understand how backend validation and database logic work in real-world projects.

While going through the repository, I found Issue #251, which addressed a bug allowing users to create multiple providers with the same name and type—for example, two “Test” VM providers. This caused confusion and potential data issues. The expected behavior was that the application should prevent duplicates and show a clear error message.

To fix this, I created Pull Request #535, titled “[FIX]: Added UNIQUE constraint to database and error handling to the server for duplicate providers.” In this fix, I enforced the validation directly at the database level by adding a UNIQUE(provider_name, provider_type) constraint to the providers table schema. I also introduced a custom DuplicateProviderError class, updated the business logic to catch this specific error, and modified the controller to return an HTTP 409 Conflict response whenever a duplicate provider is detected.

This change ensures that even if multiple users try to create a provider with the same name and type at the same time, the database automatically blocks the duplication. It’s faster and more reliable than manually checking in the application code. Now, when a user tries to add a duplicate, the system shows a clear message saying “Provider with name ‘test’ and type ‘VM’ already exists.”

I verified this locally by first creating a provider named “test” under the Server type and then trying to create another one with the same name. The system immediately returned the conflict message, confirming that the fix worked as intended. Since this update involved a schema change, I deleted the existing opsimate.db file and recreated the database to apply the new constraint. I’ve also asked the maintainers for guidance on how this should be handled in development and production environments.

This contribution taught me the importance of enforcing business rules at the database level for consistency and reliability. It also gave me hands-on experience with structured error handling and how collaborative projects maintain best practices for readable, tested, and maintainable code.

Reflections

This week was all about learning in depth rather than speed. I realized that not every pull request is about adding new features—sometimes it’s about understanding how different parts of a system connect and making sure a fix doesn’t cause new issues elsewhere. Community feedback also played a huge role; it’s not just about getting code merged but about improving through discussions and learning from experienced developers. As I wait for feedback from both Cloudinary and OpsiMate maintainers and finish my Hacktoverfest journey, I'm exploring other projects that excites me. Hacktoberfest has been a truly rewarding experience, helping me grow both technically and collaboratively.

Thank you for following my journey!

Continuing The Hacktoberfest with Cloudinary

Dharam Ghevariya — Tue, 28 Oct 2025 13:35:14 +0000

I am very happy to continue sharing my open-source journey through this second update of Hacktoberfest. In my previous blog, I discussed how I began contributing to Cloudinary's open-source projects, the process of setting up monorepos, and how I made my first two pull requests. This time, I want to talk about what happened next — the waiting period, the reviews, the feedback, and the new challenges that came my way.

Like many open-source contributors experience, getting pull requests reviewed can sometimes take a while. Maintainers often receive hundreds of submissions during Hacktoberfest, so patience becomes an essential part of the process.

The first issue I had worked on was #237, and you can view my pull request here: PR #238. The change I made was quite simple — just three lines of code — along with the addition of proper test cases to ensure functionality. You can read the full explanation of the change in the PR discussion. Despite the simplicity, the reviewer appreciated the clarity and attention to testing. That feedback made me realize something important: a “feature” doesn’t always mean a large addition of code. Sometimes, even a few well-written lines can enhance the functionality and stability of a project significantly. This experience taught me that quality and understanding are more valuable than quantity when contributing to open-source.

The next issue I had worked on was #233, which was a small bug related to escaping special characters in overlay text transformations. I had already explained the fix for this bug in my previous blog, but I later received a review confirming that the fix worked perfectly in end-to-end testing. Since I had already added a unit test for it, there were no further changes needed. You can read the review comment here. Shortly after, both my pull requests were merged, and the maintainer mentioned me to the all-contributors bot, officially adding my name to the contributors list of the repository. This was one of the most exciting moments for me because it made my contribution visible to everyone. On top of that, I also received an invitation link for the Cloudinary Hacktoberfest swag pack — a small but meaningful token of appreciation from the team. It reminded me that in open-source, patience and effort are always rewarded.

After those successful contributions, I decided to take on another issue from the same repository — #232. This one was quite different and more complex compared to the previous ones. The bug was about users being unable to use image transformations on images larger than 25 megapixels. I tried fixing this issue through PR #241, but it turned out that the changes I made were affecting other image transformation plugins in the library. The reviewer suggested rethinking the approach to make sure the fix worked consistently across all transformation modules. I am still exploring a better and cleaner solution for this bug. It is definitely a challenging one, but it has also been a great learning experience in understanding how multiple components interact within a complex codebase.

Looking back, this phase of Hacktoberfest has been extremely rewarding — not just because of the merged pull requests, but because of what I learned along the way. I learned that even small changes can have a big impact if done right. I understood that communication and patience are just as important as technical skills. Most importantly, I realized that open-source development is about teamwork, consistency, and the willingness to improve, not just about quick results.

I am still working on the last bug mentioned above and am quite excited to see how it evolves. Regardless of how it turns out, I know I will come out of it having learned something valuable. Once again, I am thankful to the Cloudinary team for their guidance and support, and to the Hacktoberfest community for giving me the opportunity to be part of something truly collaborative and meaningful.

Thank you for following my blog series, and I look forward to sharing more updates soon!

Implementing Token Count Optimization in repo-contextr

Dharam Ghevariya — Sun, 26 Oct 2025 18:55:27 +0000

Inspired by Repomix's Token Count Optimization feature, which I had explored in my previous blog, I decided to add a similar feature to my own project, repo-contextr. The idea was to help developers quickly find out how many tokens their repository would take when used with large language models. This helps plan for context limits and estimate API costs more easily.

Before starting the development, I created a feature request issue: Issue #18. The goal was to use the Tiktoken library by OpenAI for accurate token counting.

About Tiktoken:

Tiktoken is OpenAI’s fast tokenizer that can count tokens exactly as OpenAI models like GPT-3.5 and GPT-4 do. It’s widely used by tools like LangChain and LlamaIndex to calculate how much text fits into a model’s context window. Instead of guessing based on character length, it uses the same algorithm as real LLMs, giving developers a more accurate way to measure cost and context.

For the first version, I decided to start simple. Instead of integrating Tiktoken right away, I used an easier method that assumes one token for every four characters. This made it possible to test the idea quickly and get early feedback without adding a heavy dependency. Later, I planned to replace this logic with the real Tiktoken library in the next iteration, tracked under Issue #19.

Implementation Details

To build this feature, I started by creating a new branch just for this work. The idea was to keep my main branch stable and make development easier to manage. I wrote new modules for three main tasks — token counting, formatting, and CLI integration. The token_counter.py module handles the token count logic. It scans each file, skips binary files, and counts tokens using the four-character approximation. The results are also combined at the folder level to show the total token count per directory.

The token_tree_formatter.py module formats the results into a simple tree structure. It uses characters like ├── and └── to show folders and files clearly. This layout looks consistent with repo-contextr’s current output and helps developers easily see which parts of the repository take up more tokens. Files are sorted by size, and directory totals make it easier to find large sections quickly.

I also added new CLI options for users. These include --token-count-tree to show the full token tree, --token-threshold N to filter smaller files, and --tokens to show only the total token estimate. The feature blends with the existing CLI commands, so users can see token data directly in the usual output. Along with this, I updated cli.py, package.py, and report_formatter.py to support token-related data. Everything was tested to ensure it worked smoothly with the rest of the app.

Conclusion

This new feature adds more value to repo-contextr by letting developers estimate how big their repository is in terms of tokens. It helps identify which files or folders are the most token-heavy, making it easier to plan for LLM context limits and costs.

Even though this first version uses a simple character-based estimate, it sets a strong foundation for future improvements. The next step will be to integrate OpenAI’s Tiktoken library for accurate token counts. This project also reminded me how useful it is to keep work organized — using feature branches, writing clean and simple code, maintaining documentation, and keeping the Git history neat by squashing commits.

Token Count Optimization feature on Repomix

Dharam Ghevariya — Fri, 24 Oct 2025 01:39:56 +0000

For this week, I had to extend my repo-contextr project with some additional features. However, this time the catch was that we didn’t have a feature requirement beforehand. Our professor gave us a CLI tool link called Repomix.

Repomix is a command-line tool that helps developers analyze and visualize their codebase for AI processing. It measures metrics like token usage, file composition, and repository structure, allowing users to optimize how their code is represented when interacting with large language models (LLMs).

While going through the user guide, I got interested in the Token Count Optimization feature. This caught my attention because I already had a feature for counting tokens in my project — though it was a rough estimate, treating each word as a single token. However, working on this project taught me that tokenization doesn’t work that way, especially when dealing with LLMs.

To elaborate on the Token Count Optimization feature — it’s used to understand how much of your codebase would “cost” in terms of LLM context tokens when processing your query. Running

repomix --token-count-tree produces a hierarchical visualization showing token counts across your project structure. You can also apply thresholds, such as

repomix --token-count-tree 1000, to focus on larger files. This helps identify token-heavy files, optimize file selection patterns, and plan compression strategies when preparing code for AI analysis.

Diving into the Implementation

First, I used GitHub’s code search to look for "token count tree", which led me to the configuration schema and the main orchestration in calculateMetrics.ts. GitHub’s search gave me an overview of the file structure, implementation details, and references to where the feature was used in other files.

However, I quickly realized that the feature was quite complex, and navigating through multiple parts of the program in the browser-based GitHub interface was becoming difficult. That’s when I decided to set up the project locally in my code editor.

After setting it up, I used

git grep "tokenCountTree"

from the terminal, which showed me everywhere this configuration option appeared. This revealed the data flow from CLI parsing → configuration → metrics calculation → output formatting.

For each major component, I opened the file in VS Code and used “Go to Definition” on every import and function call. This helped me build a mental map of how different modules connected. Whenever I encountered unfamiliar patterns, I used GitHub Copilot Chat to clarify things instead of getting stuck. This made the learning process much smoother since it can get quite complex jumping from one concept definition to another on the internet.

Understanding the Architecture

To give you an overview, Repomix uses a vertical slice architecture, where each type of metric calculation has its own self-contained module while sharing common infrastructure.

However, token calculation was handled differently — it used the tiktoken library from OpenAI.

You can see its implementation here.

In my repo-contextr project, I implemented a similar feature that calculates the total token count of the entire codebase — although in my case, it’s equivalent to the total number of words.

Exploring Parallelism and Task Execution

One thing I’m still figuring out is how workers run tasks in parallel and the role of the TaskRunner abstraction.

After tracing through processConcurrency.ts, I discovered that Repomix uses Tinypool to manage a pool of reusable worker threads.

The TaskRunner wraps Tinypool with a simple run(task) API — when you call it, Tinypool queues the task and assigns it to an available worker.

The clever part is TASKS_PER_THREAD = 100:

With 500 files on 8 cores, it creates only 5 workers instead of 8, avoiding unnecessary thread startup overhead.

What still confuses me is Tinypool’s internal scheduling — when Promise.all() submits 500 tasks simultaneously, how does it decide which worker gets which task? I also don’t fully understand when to use runtime: 'worker_threads' vs runtime: 'child_process'.

My Plan for Repo-Contextr

I liked the idea of separating the token count for each file, so I plan to implement this feature in my repo-contextr project as well.

However, I won’t be implementing actual tokenization in the context of LLMs or using parallelism at this stage.

Still, exploring Repomix has given me a clearer understanding of how large-scale tools are structured — from CLI parsing to concurrent task orchestration — and it has definitely influenced how I’ll approach the next iteration of my project.

First Week of Hacktoberfest

Dharam Ghevariya — Sat, 11 Oct 2025 14:19:22 +0000

I am very happy to share that I am participating in the month-long open-source event called Hacktoberfest! This global event encourages developers from all over the world to contribute to open-source projects and learn from real-world codebases. During this period, open-source projects welcome contributions, and developers like me get a great opportunity to work on live projects, understand how large systems work, and collaborate with other contributors. Events like this help both contributors and maintainers, on one hand contributors get hands-on experience while maintainers get help improving their projects through community pull requests.

After spending some time searching for good projects, I decided to contribute to Cloudinary's community project, Next Cloudinary SDK. I got to know about this organization from the Digital-Ocean discord channel. Cloudinary is a platform that helps developers manage, optimize, and deliver images and videos efficiently across the web. In simple words, it helps websites handle media faster and smarter without worrying about manual optimization or delivery. In this bigger purpose project, the Next Cloudinary SDK makes it very easy to use Cloudinary inside a Next.js app. It provides React components, hooks, and utilities that allow developers to display, transform, and optimize images with just a few lines of code. Basically, it acts like a bridge that connects Cloudinary’s services with Next.js so developers can build fast, image-friendly websites easily.

The first step in my contribution journey was setting up the project and tools on my local system, which I would say was the most challenging part. I started by cloning my forked repository, and very soon, I faced my first challenge, which was understanding how a monorepo works. In simple words, a monorepo (short for “monolithic repository”) is a single repository that contains multiple small projects or packages instead of maintaining them separately. This setup makes it easier to manage related codebases and their dependencies. In this particular project, they were using pnpm-workspace.yml to define and link all the packages. Once I understood how the monorepo worked, everything started to make more sense. Honestly, GitHub Copilot helped me a lot during this part. It guided me like a mentor while setting up the project, explaining what each part of the configuration was doing and helping me debug setup errors quickly.

Once the setup was done successfully, I started exploring the issues of the repository to find something I could work on. After going through a few of them, I found Issue #592 that I felt confident to work on. Interestingly, this issue was not in the main next-cloudinary repository but in another related one — cloudinary-util (Issue #237). So, I had to set up one more project locally, but this time it was very easy since I was already familiar with the project structure. This issue was about adding new functionality to the cropMode, so that users could use it as a cropping plugin while using this library. Once I understood the logic, I made the required code changes and created a pull request. The project also had proper test cases, so I added three new tests that covered my code changes to ensure everything worked as expected.

By this time, I was much more comfortable with the codebase and started understanding how things were structured. So, I decided to take up another issue from the same repository — Issue #233. This one was a small bug related to the overlay text functionality. The problem was that when users entered consecutive special characters such as ".", ",", or "/", the code was only escaping the first character but not the rest. This caused issues in the generated URL because certain characters like commas have special meanings in Cloudinary’s syntax. To fix it, I simply replaced the replace() function with replaceAll() to make sure all the occurrences were properly escaped. You can see the fix here: Pull Request #240. Even though it was just a few lines of code, my professor always says that smaller pull requests are easier to review and merge — and they are equally important in open-source projects because they improve reliability and maintain consistency.

So far, these are the two contributions I have made during the first week of Hacktoberfest. I am still waiting for feedback and reviews from the maintainers, which is quite understandable because this event brings a huge number of pull requests for them to review. I think waiting patiently is also part of the learning process. I am now exploring another issue in the same project and also looking for new repositories to contribute to. In my next blog, I will share another interesting issue that I am currently working on and how this whole open-source journey is helping me learn and grow as a developer.

Thank you...!

Rewriting the Codebase: repo-contextr’s Week 6 Refactor Journey

Dharam Ghevariya — Fri, 10 Oct 2025 22:24:27 +0000

This week was the cleanup week for repo-contextr!

After devoting the first five weeks solely to feature development, I realized we had reached the point where code quality and maintainability needed attention. Week 6 was therefore dedicated entirely to refactoring and restructuring the project.

Background: The Early Design

At the beginning of the project, I followed a straightforward design pattern, separating the functionality into two main modules: commands and utils. The commands module was meant to contain the main features and logic of the tool, while the utils module would host supporting functions to help those features run efficiently. However, as development progressed, utils started to grow beyond its intended purpose. It became a large collection of loosely related functions — many of which were actually part of the tool’s core logic. Over time, this blurred the boundary between modules, and the design pattern I had initially set out to follow began to fade away. This was not only making the code difficult to navigate but also making it harder to onboard new contributors. It became clear that before adding any new features, the internal structure had to be cleaned up.

The Previous Code Structure

src/contextr/               # Main package
├── __init__.py
├── cli.py                  # CLI argument parsing
├── main.py                 # Application entry point
│
├── commands/               # Command implementations
│   ├── __init__.py
│   └── package.py          # Main command(328 lines - MONOLITHIC)
│
└── utils/                  # "Utils" anti-pattern package
    ├── __init__.py
    └── helpers.py          # ALL functionality (376 lines)

The Refactor Plan

To improve the maintainability and clarity of the codebase, I spent some time exploring well-structured open-source Python projects. A common theme I noticed was that each core functionality was isolated in its own dedicated module, with clear boundaries between responsibilities. Inspired by this, I decided to completely remove the utils module and distribute its contents into purpose-specific packages. Before beginning, I created a new Git branch named refactor/improve-codebase to ensure all the refactor work remained isolated from the main branch until it was stable. This allowed me to make incremental changes, test them thoroughly, and later merge the work in a clean, single commit.

Implementation Details

The professor had also pointed out during evaluation that having a utils module at the forefront was a design weakness in any serious project. After reviewing it, I realized that everything inside utils could be reorganized into focused modules such as discovery, processing, git, output, and config. Additionally, the logic responsible for generating reports could be encapsulated into a dedicated class, RepositoryReportFormatter, improving testability and readability. This new modular approach helped separate concerns and made the code easier to extend and maintain.

Throughout the process, I maintained a clean and disciplined Git workflow. I committed the changes in three logical stages and later used interactive rebase to squash them into a single, well-documented commit. This ensured that the main branch retained a clean and readable history. Once everything was reviewed and verified, I merged it into the main branch. You can see the commit here: 1f9aff6. This workflow made the refactoring process organized, reversible, and transparent.

The New Structure After Refactor

src/contextr/
├── cli.py                    # CLI interface (argparse)
├── main.py                   # Entry point
│
├── commands/                 # Command implementations
│   ├── __init__.py
│   └── package.py            # Main orchestration (83 lines)
│
├── config/                   # Configuration management
│   ├── __init__.py
│   ├── settings.py           # Application constants
│   ├── toml_loader.py        # TOML configuration loading
│   └── languages.py          # Language/syntax mappings
│
├── discovery/                # File & directory discovery
│   ├── __init__.py
│   └── file_discovery.py     # File finding, filtering, path validation
│
├── processing/               # File content processing
│   ├── __init__.py
│   └── file_reader.py        # Content reading, binary detection
│
├── git/                      # Git repository operations
│   ├── __init__.py
│   └── git_operations.py     # Git info, recent files, root detection
│
├── formatters/               # Output formatting
│   ├── __init__.py
│   └── report_formatter.py   # Report generation (230 lines)
│
├── statistics/               # File analysis & metrics
│   ├── __init__.py
│   └── file_stats.py         # Statistics calculation (115 lines)
│
└── output/                   # Display formatting
    ├── __init__.py
    └── tree_formatter.py     # Tree structure generation

Version Control Workflow

This refactor week taught me the importance of writing code for humans first, and machines second. Design patterns that seem fine during early prototyping may not scale as a project matures. Keeping code modular, organized, and easy to understand is what makes a project sustainable in the long term. I also learned that avoiding catch-all directories like utils encourages meaningful boundaries and accountability within the codebase. Refactoring also made me appreciate Git’s advanced capabilities. Using branches for isolation, rebasing for history cleanup, and well-scoped commits for traceability all contribute to a cleaner development lifecycle. Most importantly, I learned that restructuring a codebase is not just about rearranging files, it’s about improving readability, maintainability, and paving the way for future contributors.

You can check out the project on GitHub here:

👉 repo-contextr on GitHub

Adding TOML Config File Support to an Open Source CLI Project

Dharam Ghevariya — Fri, 03 Oct 2025 13:48:44 +0000

In Week 5 of my Open Source Development course, the task was to add a new feature to another student’s repository. I decided to work on the project Repository-Context-Packager. This tool helps package useful information about a repository so it can be used later.

The Problem

Right now, to run the tool you need to type a long command every time. For example:

repo-packager "PATH/TO/REPO" \
  --output "output.txt" \
  --include "*.js" \
  --exclude "*test*" \
  --max-file-size 1024 \
  --format "json"

If you always use the same options, typing this again and again is not very user-friendly.

The Solution: TOML Config File

To fix this, I added support for a TOML config file. This means you can create a simple file called .repo-packager-config.toml in your project folder:

output = "output.txt"
include = "*.js"
exclude = "*test*"
max_file_size = 1024
format = "json"

Now, the tool will read these values automatically. You don’t need to type them in the command line each time.

How I Built It

To handle TOML files, I chose smol-toml, a lightweight library that is simple and straightforward to work with.

Here’s the main function I wrote:

export function loadConfig() {
  const configFileName = ".repo-packager-config.toml";
  const configPath = path.join(process.cwd(), configFileName);

  // If config file doesn't exist, return empty config
  if (!fs.existsSync(configPath)) {
    return {};
  }

  try {
    const configContent = fs.readFileSync(configPath, "utf-8");
    const config = parseToml(configContent);
    return config;
  } catch (error) {
    console.error(
      `Error parsing TOML config file '${configFileName}': ${error.message}`
    );
    process.exit(1);
  }
}

This function first checks if the config file exists in the current directory. If it does, it opens the file, reads the contents, and parses it into an object so the program can use the values as options. If the file does not exist, it simply returns an empty object.

Working With the Maintainer

Before I began coding, I opened an issue in the repository to explain my feature idea and to get the maintainer’s feedback. This step was important because it made sure the idea was useful and aligned with the project. After the maintainer approved the idea, I created a draft pull request. A draft PR is useful because it lets others see that you are actively working on the feature, even if it’s not finished yet. Once I completed the feature, tested it, and updated the README with instructions, I changed the pull request from draft to ready for review. This signaled to the maintainer that the work was complete and ready to be checked. The full changes can be seen in Pull Request #16.

Reviewing the Same Feature in My Repo

Now the roles were reversed, I was the maintainer and got the feature contribution. One of my classmates suggested the same feature in my own project, repo-contextr, and opened PR #16.

To properly test their changes, I first added their fork of my repository as a new remote:

git remote add bhchen24 https://github.com/BHChen24/repo-contextr.git

This gave me access to their version of the repository. Next, I checked out the branch they had created for the feature:

git checkout -b issue-15-feat-support-using-a-TOML-dotfile-config-file bhchen24/issue-15-feat-support-using-a-TOML-dotfile-config-file

By doing this, I created a local branch that pointed directly to their work. This allowed me to pull down their changes and run the code on my own machine. Running it locally was important so I could confirm that the new TOML config feature worked as expected.

During my review, I noticed a few issues where the implementation didn’t fully meet the requirements. I started a review on GitHub, added comments, and opened a discussion thread with my feedback (review link)[https://github.com/dharamghevariya/repo-contextr/pull/16#pullrequestreview-3291624639]. The contributor then made the necessary fixes and pushed the updates to their branch.

Once I confirmed the fixes worked, I merged the changes into the main branch of my project with the following steps:

git checkout main
git merge issue-15-feat-support-using-a-TOML-dotfile-config-file
git push origin main

After pushing to GitHub, the pull request was automatically marked as merged. This completed the process and added the new feature into my project.

Learnings

This week’s task helped me learn both sides of open source work:

As a contributor: suggest a feature, open a PR, and finish it with tests and docs.
As a maintainer: review someone else’s PR, give feedback, and merge changes.

It showed me the value of good communication, small steps (using draft PRs), and always testing code locally before merging.

Working with the two parallel branches in Git

Dharam Ghevariya — Fri, 26 Sep 2025 21:10:47 +0000

This week was truly eye-opening as I dove into the concepts of branching and merging in Git. At first, the workflow felt a bit tricky to grasp, but after carefully going through the readings from the Git book:
3.2: Basic Branching and Merging, 3.3: Branch Management, 3.4: Branching Workflows

I started to understand the power behind these features. Once I practiced them in Lab-03, it honestly felt like working with a Git-powered time machine where I am managing multiple timelines of a project and then bringing them back together.

Parallel Feature Development

For the lab, we had to build two features in parallel branches and later merge them into the main branch using different merging strategies. Here’s what I worked on:

1. Last Modified Timestamps

The goal was to display file modification timestamps in each file header of the output.

Example:

### File: src/main.js (Modified: 2024-01-15 14:30:22)
const helper = require('./utils/helper');

To implement this, I used Python’s subprocess library to run git log commands for individual files and extract the last modified information.

I first created the issue on GitHub (Issue #9), and then worked on it in a dedicated branch.

2. Statistics Enhancement

This feature expanded the summary section of the tool by adding more detailed statistics such as:

Total files and total lines
Breakdown of file types
Largest file details
Average file size

Example output:

## Summary
- Total files: 15
- Total lines: 342
- File types: .js (8), .md (3), .json (2), .css (2)
- Largest file: src/main.js (89 lines)
- Average file size: 22 lines

I have done this by going over files and keep track of the type counts, finding the largest file by line count, and then returning the structured result back to the caller. The helper functions included logic to group file types, identify the largest file, and compute averages.

Before start working on the feature implementation, I had created an Issue #10 to describe the functionality expected.

Merging the Timelines

Once both features were implemented, it was time to bring them back to the main branch.

I tried merging the branch for Issue #9 first. As It was branched off of the main branch the merge was fast-forward and was done in a single commit.

But when it came to merge the second Issue #10, I faced a merge conflict. It was due to a README.md file, where the Issue #10 branch had changed the same line of code which Issue #9 had changed. It confused git and caused the merge conflict. To fix this I used the vs code editor's conflict resolver feature, which provides very clean UI of current and the upcoming features. So it created a commit when I resolved the conflict.

Overall, This lab taught me how powerful Git branching and merging really are. At first, it was overwhelming to handle multiple branches and merge strategies, but once I practiced, it felt natural and even fun.

Raising PR to Another Repository

Dharam Ghevariya — Sat, 20 Sep 2025 21:41:30 +0000

For lab-02, we were asked to implement a feature for another classmate's repository. I decided to contribute to the Repository-Context-Packager, which is a command-line tool that analyzes repositories and generates a single file containing repository context. This project was written in JavaScript using Node.js.

Getting Started: Fork, Setup, and Initial Issues

To contribute to this repository, I had to fork it to my GitHub account since I wasn't authorized to push directly to the original repo. During the initial setup, something immediately caught my attention: the node_modules directory was being tracked in Git, even though it should have been ignored through the .gitignore file.

This led me to file my first issue - Issue #9 regarding this caching problem. The author had node_modules listed in .gitignore, but it wasn't working because the files were already being tracked by Git before being added to the ignore file. I created a local branch for this issue, solved it by using git rm --cached to untrack the files, and raised PR #10.

Feature Development: Implementing the Recent Changes Filter

After resolving the initial issue, I moved on to implementing the main feature: a --recent flag that filters and packages only files modified within a specified number of days based on Git commit history.

Implementation Details

The feature development involved several technical challenges and decisions:

Git Integration:
Initially, I considered using filesystem timestamps (fs.stat().mtime) to determine file modification dates. However, I quickly realized this approach had significant limitations. Accessing file timestamps are very tricky thing to do as it changes according to the operating systems. Moreover, the tool was specifically developed for the git repositories so it made me opt for a Git-based approach using the simple-git library:

Code Review Experience

I also received a similar PR on my repository - it was the same feature I had implemented for the original author's repository, the difference was just in the language used.

For the review process, I added the contributor's Git repository to my local remotes, then created a local branch pointing to their PR branch. This way I was able to test the feature locally. I found two issues related to code structure and created review threads for them. Once the contributor updated the code with the desired changes, I closed the threads and merged the PR.

During the review, it was important for me to keep the code style consistent as I had been following it, so I created threads to maintain that consistency.

Conclusion

Throughout this whole process, I got to know that when contributing to others' repositories, you have to understand their style so you can follow it to contribute effectively. When you start working on a feature, you may find other bugs to file and solve if possible. In the open source world, this is the best thing to receive and give.

While doing code review, it was very important for me to keep the code style consistent as I had been following it, so I had to create threads for that. This experience taught me that open source development is not just about writing code - it's about understanding project conventions, maintaining quality standards, and building relationships within the community.

The collaborative nature of open source means every contribution, whether fixing bugs or implementing features, helps improve the project for everyone. This cycle of giving and receiving makes the entire ecosystem stronger and more reliable.

Introducing repo-contextr v0.1

Dharam Ghevariya — Sat, 20 Sep 2025 18:32:43 +0000

Release 0.1 of repo-contextr

Finally, at the end of week 3, version 0.1 of repo-contextr is out! 🎉 This marks my first real open source project release, and honestly, I'm still amazed by how it all came together.

This release represents the foundation of what the tool will look like at full release. When I first set up this project, I had no idea it would evolve the way it has. It's incredible to see how small pieces of work can create something genuinely useful. Although this isn't the end of the project, I can already see a clearer picture of what the final product will become.

The tool solves a simple but annoying problem: sharing your entire codebase with AI assistants like ChatGPT or Claude without having to copy-paste files one by one.

A Glimpse of repo-contextr

It scans your entire project, gathers all the important information, and packages everything into one clean, organized text file that's perfect for sharing with AI tools.

The tool is pretty straightforward in what it does. It looks through your project files, grabs your git information like commit details and branch name, and puts everything together in a nice structured format. You can also filter which files to include - for example, if you only want Python files, just add --include "*.py" to the command.

# Basic usage - analyze current directory
contextr .

# Filter for specific file types
contextr . --include "*.py"

# Save output to file for sharing
contextr . --include "*.py" --output context.txt

The best part is that the output is really well organized. It creates sections for your git information, shows your project structure like a file tree, and includes all your code with proper formatting. This makes it super easy for AI assistants to understand your entire codebase at once, instead of you having to explain everything piece by piece.

My Learnings!

During this release 0.1 development, I got to explore Git in ways I never had before. This project has taught me how to manage code changes, work with others, and understand how open source projects actually work.

Git Skills:

It is very hard at the start to wrap your mind around the concept of git and workflows related to it. Once you get the hang of branches, commit histories, pushing to remote repos and all, it becomes very easy. Then you won't have to think much before running any git commands.

GitHub Skills:

On the other side of version control, which is the collaboration tool - GitHub. I believe this tool is also a major part of the workflows connected to git. I learned to create issues, PRs, and work with project authors and contributors during this phase.

Problems:

It is quite obvious that working in an asynchronous manner has the problem of not coming to a result one would want to have at their own time. You have to understand others and help the contributors through the issues they are facing. I had the chance to get myself in this situation, where I and another contributor both missed the deadline of this release. But we calmly understood each other's issues and tried to resolve them, and completed this release.

One other personal problem that I got into and am still in, is the name of the tool. So initially I wanted to publish this package to PyPI so it can be installed with pip. But in the middle of the project I got to know that the "contextr" CLI tool name was already taken by someone. So I had to change the name of the tool to "repo-contextr" and that confused the contributor, resulting in unnecessary issues. I am still working on this and probably will be able to publish it in the next release.

Try repo-contextr Yourself

Want to see what all the excitement is about? Here's how you can try repo-contextr:

🔗 GitHub Repository: github.com/dharamghevariya/repo-contextr

# Install directly using pipx (recommended)
pipx install git+https://github.com/dharamghevariya/repo-contextr.git

# Try it on any project
contextr . --include "*.py"