My First Open Source Contributions: A Technical Deep Dive
Amar Kumar Thakur
5 min read · August 2026
INTRODUCTION
My first meaningful open source contributions are now merged into hflow, an open-source SDK for building data-quality, processing, enrichment, and curation pipelines for robotics and Physical AI applications.
I contributed two pull requests to the project.
One focused on improving the developer experience around code quality and pre-commit tooling.
The other addressed an important platform-support gap that I discovered while developing on Windows.
Both were relatively small contributions in terms of functionality.
But they taught me something important about contributing to production open source projects:
You don't always need to build a major feature to make a meaningful contribution.
Sometimes, fixing the friction around the project is just as valuable.
PROJECT OVERVIEW
hflow is maintained by Hebbian Robotics, a Y Combinator S26 company focused on physical AI infrastructure.
The project provides tooling for data pipeline orchestration in robotics environments.
That made it an interesting project to contribute to, particularly because the problems I encountered were directly connected to the developer experience of working with the repository.
Repository: https://github.com/Hebbian-Robotics/hflow
Maintainer: kstonekuan (@kstonekuan on GitHub)
CONTRIBUTION #1: IMPROVING THE DEVELOPER EXPERIENCE
Pull Request: https://github.com/Hebbian-Robotics/hflow/pull/15
Status: Merged on August 19, 2026
Commits: 2
THE PROBLEM
The repository already had strict code-quality standards enforced through CI/CD.
The problem was that contributors didn't have the same checks available during their normal local development workflow.
That meant someone could write code, commit it, push it, and only discover a formatting or linting problem after CI failed.
Those failures were preventable.
The project already knew what good code looked like.
The local development environment simply wasn't enforcing those expectations early enough.
THE SOLUTION
I approached the problem as a developer-experience issue rather than adding another feature.
The solution had three parts.
1. EditorConfig
I added an .editorconfig configuration to make basic editor behaviour consistent across different IDEs and editors.
The configuration covered:
- UTF-8 character encoding
- LF line endings
- Required final newlines
- Trailing whitespace removal
- Four-space Python indentation
- A 100-character Python line length
- Two-space YAML indentation
The important part was keeping these settings aligned with the existing pyproject.toml configuration.
The repository already specified a 100-character line length through tool.ruff.
The goal wasn't to introduce a new coding standard.
It was to make the existing standard easier to follow.
2. Pre-commit Hooks
I added pre-commit configuration so code-quality checks could run before changes reached CI.
The project uses ruff for Python linting and formatting.
The configuration pinned ruff to version 0.16.2 and included:
ruff check --fixruff format
Version pinning was synchronized with uv.lock to keep the development environment reproducible.
This meant contributors could catch common issues locally instead of waiting for CI to report them.
3. CONTRIBUTING.md
The final part was documentation.
I added a dedicated pre-commit setup section explaining how contributors could install and use the hooks.
The documented installation methods included:
uv run pre-commit installpipx run pre-commit install
The documentation also explained that hooks run automatically during commits and can be executed manually with:
uv run pre-commit run --all-files
VALIDATION
Before submitting the pull request, I wanted to make sure the new configuration actually matched the existing codebase.
I ran:
uv run ruff check --fix
All checks passed.
Then:
uv run ruff format
The result was:
83 files left unchanged
That zero-diff result was important.
It showed that the new configuration wasn't introducing a new formatting standard that conflicted with the existing repository.
It was simply making the existing expectations easier to enforce locally.
MAINTAINER FEEDBACK
The maintainer later pushed a cleanup commit addressing several details:
- UTF-8 BOM removal
- Updating the hook ID to the current
ruff-checknaming convention - Refining the installation documentation
- Clarifying
uvx pre-commitversusuv run pre-commit
This was one of my first experiences seeing how open source contribution actually works beyond simply opening a pull request.
The contribution wasn't finished when I opened the PR.
Review feedback became part of the implementation process.
CONTRIBUTION #2: PLATFORM SUPPORT
Pull Request: https://github.com/Hebbian-Robotics/hflow/pull/75
Status: Merged on August 21, 2026
Commits: 6
THE PROBLEM
This contribution started with an error.
While developing on Windows, I encountered:
ModuleNotFoundError: No module named ''fcntl''
At first, an error like this can look like a local environment problem.
But fcntl is part of Python's Unix-specific system interface and isn't available on native Windows.
That raised a more important question:
Was Windows actually supported by the project?
The existing CONTRIBUTING.md didn't clearly answer that.
A Windows contributor encountering this error had no obvious way to know whether they had configured something incorrectly or whether the project simply wasn't designed for native Windows development.
INVESTIGATING THE ROOT CAUSE
I traced the problem into src/hflow/storage.py.
The module contains a direct import of fcntl.
Because that import happens at module load time, the package fails on native Windows before tests can even run.
I then checked the project's CI configuration.
The GitHub Actions workflows were running on ubuntu-latest, confirming that the project's automated environment was Linux-based.
The problem therefore wasn't simply a missing Windows dependency.
There was a genuine platform-support limitation that wasn't clearly documented.
THE SOLUTION
Instead of modifying the underlying storage implementation, I focused the contribution on documentation.
I added a dedicated platform-support section to CONTRIBUTING.md.
Platform Support
The documentation clearly identified:
- Linux: Fully supported for native development
- macOS: Fully supported for native development
- Windows: Not supported for native development because of the
fcntldependency
Windows Development
For Windows developers, the recommended approach was:
WSL2 — Windows Subsystem for Linux 2
This provides a Linux development environment without requiring contributors to replace their Windows setup.
The documentation also included the relevant technical context around the fcntl dependency and WSL2 virtualization requirements.
VALIDATION
I didn't want the documentation to be based only on assumptions.
The validation process included three parts.
1. Mechanism Verification
I confirmed the fcntl import in src/hflow/storage.py and verified that importing the package natively on Windows fails at module load time.
2. CI/CD Analysis
I reviewed the GitHub Actions workflows and confirmed that the CI pipeline runs on Linux through ubuntu-latest.
3. Documentation Validation
I used the lychee link checker to validate the documentation cross-references.
The result:
231 links checked. 0 errors.
That gave me confidence that the documentation changes weren't introducing broken references.
MAINTAINER FEEDBACK
The maintainer reviewed the contribution and made several refinements.
Heading Formatting
The headings were adjusted to sentence case so they matched the surrounding documentation.
Project Naming
References were updated for consistency with the project's preferred nomenclature.
Avoiding Duplicate Documentation
Instead of repeating existing setup instructions, the documentation was linked to the project's existing prerequisites documentation.
That follows a principle I hadn't paid much attention to before:
Keep one source of truth whenever possible.
Scope Refinement
The Docker Desktop recommendation was removed because the project didn't ship a devcontainer configuration.
That was a good correction.
It is better to document what the project actually supports than to provide theoretically possible options that aren't officially configured.
The maintainer summarized the value of the contribution by pointing out that a Windows contributor encountering the fcntl error would otherwise have no way to know whether they had broken something or whether native Windows development simply wasn't supported.
TECHNICAL STACK
The project uses several tools that were directly relevant to these contributions:
- Python: 3.11+
- Package manager:
uv - Linting and formatting:
ruff - Static type checking:
mypy - Testing:
pytest - Git hooks:
pre-commit - Editor configuration: EditorConfig
Working through the contributions required understanding how these pieces fit together rather than treating each configuration file independently.
WHAT I LEARNED
1. OPEN SOURCE IS LESS INTIMIDATING THAN IT LOOKS
Before opening my first PR, I expected code review to be much more intimidating.
It wasn't.
The maintainers were collaborative and provided clear explanations for the changes they requested.
The review process felt much more like engineering collaboration than an evaluation.
2. FINDING THE PROBLEM COMES BEFORE WRITING THE CODE
Both contributions started with a problem.
The first was:
Why are developers discovering formatting issues in CI instead of locally?
The second was:
Why doesn't the documentation explain what happens when a Windows developer encounters fcntl?
Only after understanding the problem did the implementation become obvious.
That changed how I think about open source contribution.
Don't start by asking:
"What code can I add?"
Start by asking:
"What problem is actually worth solving?"
3. DOCUMENTATION IS A REAL CONTRIBUTION
Neither PR introduced a major product feature.
One improved developer tooling.
The other improved platform documentation.
But both addressed real friction points.
Good documentation can prevent contributors from wasting hours debugging something that was never going to work in the first place.
That's real engineering value.
4. MAINTAINER FEEDBACK IS PART OF THE PROCESS
It is easy to interpret review comments as criticism.
I found it more useful to treat them as another engineering input.
The maintainer feedback improved:
- Accuracy
- Consistency
- Documentation structure
- Project maintainability
The final result was better than the initial implementation.
5. OPEN SOURCE FORCES DEEPER LEARNING
Working on these contributions required me to understand things beyond the immediate change:
ruffconfiguration- EditorConfig
- pre-commit workflows
- CI/CD pipelines
- Python platform dependencies
- Documentation architecture
- Developer experience
That kind of hands-on learning sticks differently from simply reading documentation.
You understand the reason behind the tool rather than just knowing how to use it.
IF YOU WANT TO START CONTRIBUTING
You don't need to begin by implementing a massive feature.
Start by looking for friction.
1. Find a Problem
Read the README, contribution guide, setup instructions, and issue tracker.
Look for places where contributors might get stuck.
2. Verify It
Don't assume something is broken.
Reproduce the issue yourself or inspect the existing implementation and documentation.
3. Define the Solution
Before writing code, be able to explain:
- What is wrong?
- Why does it matter?
- What should change?
- How will you verify the fix?
4. Talk to Maintainers
When appropriate, use GitHub discussions, issues, or other project communication channels to validate the approach.
A short conversation can prevent a large amount of unnecessary work.
5. Treat Reviews as Collaboration
The goal isn't to prove that your first implementation was perfect.
The goal is to make the repository better.
WHAT'S NEXT
There are still plenty of areas where I can contribute to hflow.
My next focus is:
- Identifying additional developer-experience gaps
- Contributing to documentation improvements
- Supporting community adoption of the physical AI data pipeline SDK
The first two contributions were a starting point, not an endpoint.
CONCLUSION
My first two merged contributions to hflow taught me that meaningful open source work doesn't always require writing hundreds of lines of code.
Sometimes the highest-value contribution is identifying friction that everyone has learned to tolerate.
A missing pre-commit configuration.
A platform limitation that isn't documented.
A broken link.
An unclear setup instruction.
These things look small individually.
But they compound into developer experience.
The biggest lesson I took away is simple:
Don't wait until you're an expert to contribute to open source.
Find a real problem.
Understand it properly.
Propose a focused solution.
Listen to the maintainer.
And ship it.
That's how you start.
REFERENCES
- hflow Repository
- PR #15 — Developer Experience
- PR #75 — Platform Support
- EditorConfig
- Pre-commit
- Ruff
- Hebbian Robotics
- Y Combinator
© 2026 Amar Kumar Thakur