How I Contributed to an Open Source Project Without Knowing the Framework
I'm a Ruby on Rails developer with several years of experience across various projects and technologies. Two weeks ago, after wrapping up a project, my CTO mentioned Open Mercato — he described who's behind the initiative, how fast it's growing, and why he thought it was worth getting involved.
The project is focused on ERP software — a space dominated by outdated systems that often don't even support basic integrations. Open Mercato approaches this with a modern stack, a strong emphasis on openness and integration capabilities, and active support for the latest LLM-based agentic coding techniques. The company I work for actively supports open source initiatives like this — especially ones that have the potential to be a gamechanger in their field.
For me personally, there were three reasons to give it a shot. First — I wanted to broaden my technical perspective. I believe a developer who understands more than one ecosystem simply solves problems better. Second — the project is built with TypeScript and Next.js, and I wanted to get practical experience in a JavaScript environment. I'm familiar with TypeScript, so the language itself wasn't a barrier, but Next.js was new territory. Third — I wanted to deliberately develop my skills in AI-assisted coding. Not having AI write code for me, but learning to use these tools effectively as part of the workflow.
Getting started
After setting up the project locally, I didn't jump straight into issues. First I wanted to understand what I was dealing with. I analyzed the codebase using Claude installed in the IDE, extended with dedicated plugins for reading, analyzing, and implementing code. That was a deliberate choice — the right tools make a real difference here. I asked for a breakdown of the project structure: which modules are used, how the architecture is organized, what the general conventions look like. I also asked it to check whether the project had any AI-specific guidelines files.
That's where the first surprise came in — the project has extensive AI documentation. Clear guidelines on how to write tests, how to implement code, what format to follow for PRs. That significantly sped up getting oriented in the project.
With a clear picture of the architecture and an understanding of the conventions, I started looking for a first issue. I picked something that seemed well-scoped and understandable. Finding the relevant part of the codebase wasn't difficult — the project is well tested, and the tests themselves work as documentation. Reading through them, it was straightforward to isolate the problematic area.
Then I went back to Claude — asked for an analysis of the specific code in the context of the issue. The analysis confirmed my suspicions. Next step: a fix plan. But before implementing it, I asked Claude to check whether the functions I was about to modify were used elsewhere in the project — to make sure fixing one thing wouldn't break another. The plan covered both the solution itself and the AI guidelines defined in the project.
First PRs
The first issue was about notification emails — links in outgoing messages were broken when APP_URL was badly configured. The system was using a generic panel link instead of the specific address tied to each notification type. On top of that, a missing APP_URL resulted in emails being sent with broken links instead of being blocked entirely.
The second issue was in the scheduler module running under the default development configuration (QUEUE_STRATEGY=local). Three problems: clicking "Run Now" returned a generic error instead of a clear message, the scheduler detail page crashed trying to fetch data unavailable in that configuration, and the JSON field in the forms was using a plain textarea instead of a dedicated component already available in the project.
Worth mentioning one deliberate decision: part of the issue was intentionally left out — analysis showed that implementing it would require architectural changes well beyond the scope of a bugfix. This was documented in the PR and submitted as a separate feature request. I think that kind of transparency is part of good contribution culture.
Following the project documentation, I started with a fork. Before opening a PR to the main repository, I did an internal review with our team. The PR was well described — problem, cause, solution — following the format required by the project. Worth noting: our team had no prior knowledge of the codebase, yet thanks to the thorough code and feature documentation — supported by Claude — they were able to get up to speed quickly enough to provide meaningful review, reference the proposed architecture and implementation, and add real value to the process. The internal feedback came down to one point: verify that the fixed functions don't affect other parts of the codebase. I addressed that, got internal approval the same day.
Same day I opened the PRs on the original repository. Next day — approved without remarks. Both merged.
What this comes down to
Stepping into a new project, a new framework, a new community — it sounds like a lot. But with the right approach, the barrier to entry is much lower than it seems.
A few things that helped:
- starting by understanding the project before touching any issues,
- treating tests as documentation,
- using AI deliberately as a tool for analysis and planning rather than code generation,
- picking something small and well-defined to start with.
Open source is good ground for this kind of expansion. Projects are public, the code is there to read, and first contributions don't have to be groundbreaking. They just have to be correct.
