What Makes a Good Open Source PR (Lessons From Getting Mine Closed)

Source: Dev.to

The Bug

I was digging into ClawHub’s search ranking system (ClawHub is the skill marketplace for OpenClaw) and noticed something weird: if you searched for a skill by its exact slug, it wouldn’t necessarily show up at the top. Sometimes it wouldn’t show up at all.

The root cause was in the search pipeline. Vector similarity search ran first, then lexical boosts were applied. But if a skill had low downloads and its embedding didn’t score well for its own name, the vector recall stage would just skip it. The exact slug match never got its +1.4 boost because it never made it into the candidate pool.

My PR: The Quick Fix

I added a slug recall step — after vector search, do an O(1) lookup by slug, inject it if missing. Simple and it worked.

What went wrong

• V1 was too hard‑coded. It was called out in review immediately.
• V2 missed a critical edge case: what if the user intentionally sorts by downloads? My injection would override their explicit choice.

The Competing PR

Another contributor submitted a fix that was merged instead. The key differences:

• Respect for user choices – They distinguished system defaults from user‑selected sorts, preserving explicit user decisions.
• Root‑cause fix – Instead of patching downstream, they removed the problematic code upstream.
• Demo video – A short before/after screen recording helped the maintainer verify the change quickly.
• Regression tests – They added tests covering edge cases I hadn’t considered.

What I Learned

1. Think about edge cases before submitting

For every behavior change, list at least three scenarios where it might break. If you can’t think of any, you haven’t thought hard enough.

2. Fix the root cause, not the symptom

Ask yourself: am I adding code to compensate for another piece of broken code? If yes, fix the underlying mistake instead.

3. Show your work

Include screenshots, videos, or before/after comparisons. Maintainers reviewing many PRs gravitate toward contributions that make verification easy.

4. Understand the full system

Knowing the code you’re changing isn’t enough; you need to understand the surrounding code and how it interacts.

If You’re New to Open Source

• Read existing PRs before submitting yours.
• Don’t rush — the best fix wins, not the first.
• Respond to review comments quickly and thoughtfully.
• It’s okay to get a PR closed; one closed PR can teach more than ten merged typo fixes.

This post is based on my experience with ClawHub search ranking PRs. The competing PR was objectively better, and I’m grateful for the learning opportunity.