My First Open Source PR: How a Korean README Fix Merged in Under an Hour

Introduction

On October 3, 2026, I merged my first open source pull request. It didn't touch a single line of runtime code, and it didn't fix a bug you could reproduce. It updated one file README.ko-KR.mdin oh-my-opencode-slim, a multi-agent plugin for OpenCode with more than 9,000 stars.

The whole thing went from issue to merged in 59 minutes. I couldn't have planned a softer landing into open source if I'd tried, and that's exactly why it's worth writing down.

If you're circling your own first contribution, here's the honest version of the story: the technical work was the easy part. The hard part was believing my perspective counted. This post walks through how it started, the move that made it painless, and five lessons you can copy for your own first PR.

The Beginning: A README That Fell Behind

I'm a user of the project, not a core contributor. I use oh-my-opencode-slim to coordinate a team of AI agents inside OpenCode, and I read the Korean README the way most users do, to set things up.

That's how I noticed the drift. The Korean README had fallen behind the English one. The gaps weren't dramatic, but they added up:

• Setup instructions still described a --skills=force command and installer-managed skill updates that no longer matched how the plugin handles bundled skills.
• Several agent-role descriptions were still in English, so half the roster was unexplained in the Korean docs.
• Literal translations made terms like "work graph" and "evidence path" harder to parse than the English originals they were supposed to clarify.

Docs are a product surface. When setup steps don't match the software, readers don't blame the docs. They assume they messed up. I caught myself re-reading the same section twice because an instruction no longer applied.

For a while, I sat on it. The project has thousands of stars and an active maintainer. My reasoning went something like: someone closer to the code should handle this. I'm a user.

Then I flipped it. The gap existed because the people closest to the code write in English. I read Korean, I used the tool, and I noticed the mismatch. That's the whole job description for this fix. Nobody else was positioned to spot it.

The Turning Point: File the Issue First

My first instinct was to write the translation and open a pull request. Instead, I opened issue #1422 first.

The issue did four things:

1. It itemized the drift. Not "the docs are outdated". A specific list of stale instructions, untranslated sections, and unclear terms.
2. It showed history. I referenced the three earlier sync efforts (#502, #727, and #935) so the maintainer could see this was a recurring pattern, not a one-off complaint.
3. It set the scope. One file. Documentation only. No changes to commands, configuration keys, model IDs, or agent names. Ambiguities in the English source would be flagged, not silently reinterpreted.
4. It claimed the work. I ended with one sentence: "I'd like to contribute a PR for this update."

That last line changed everything. I wasn't asking permission to touch someone's project. I was telling the maintainer exactly what to expect, in a way they could say no to.

Nobody replied to the issue. Maintainers are busy, and silence is normal. The issue still did its job. It put the scope on record. Ten minutes later, I opened PR #1423.

The translation itself took not that long. The interesting constraint wasn't vocabulary, it was voice. The English README introduces the agents with a mythological tone "seven divine beings" and all that. Korean readers deserve the same voice, not a stiff technical restatement. So I rewrote awkward literal translations, translated the role descriptions, and kept the myth intact.

I also practiced restraint. Contributor-generated sections stayed untouched. Where the English source was ambiguous I flagged it in the PR instead of inventing an answer. The final diff: one file, +149/−132, one commit.

The Outcome: Issue to Merge in 59 Minutes

The public timeline still makes me smile:

Issue to merge: 59 minutes.

That number is flattering, but it isn't the point. The work happened before the clock started. The issue-first move is what made the merge a formality. The scope was already agreed on in writing, so the maintainer had nothing to negotiate.

The review is worth mentioning too. Two minutes after I opened the PR, Greptile flagged a P2 finding. My new Council instructions told readers to type council or @council, but on a default install there are no Council member presets, so the keyword won't trigger anything until members are configured. Fair catch. The maintainer merged the docs update anyway, and that setup condition is still on my list for a follow-up PR.

The lesson stuck: when you document a feature, check the path that gets a new user to it.

One more detail from the PR that I'd repeat every time: the validation section. I ran git diff --check, verified link and image targets, checked code fences and anchors, and confirmed contributor sections were unchanged. I couldn't run bun run check:ci, the typecheck, or the test suite, because development dependencies weren't installed in my environment. So I said that, in plain text, instead of hiding it.

For a docs-only change, that honesty did more than a green checkmark I couldn't produce.

So what changed? The repo I use every day now has accurate Korean documentation. And in GitHub's eyes, I went from user to contributor. The gap between those two labels turned out to be one issue, one file, and one focused sitting.

Key Takeaways for Readers

If you're planning your first contribution, here's what I'd carry forward.

1. File the issue before you write the PR. An issue is a cheap way to de-risk a pull request. It gives the maintainer a chance to redirect scope before you invest hours, and it gives your PR an agreed target. Ten minutes of writing saved me a rewrite.

2. Documentation is a real contribution. Translation drift is a bug for the people who need those docs. You don't have to touch the engine to make the project dramatically better for thousands of readers.

3. Keep the diff boring. One file, one purpose, one commit. My PR body said it plainly: "Only README.ko-KR.md is changed. No runtime code changes." A reviewer can say yes to that in minutes. Scope creep is what turns a friendly PR into a debate.

4. Be explicit about what you didn't do and couldn't verify. I listed the checks I ran, named the ones I couldn't run, and flagged source ambiguities instead of guessing. Transparency beats the appearance of completeness especially on your first PR, when trust is the thing you're building.

5. Treat review feedback as free expertise. A bot found a real gap in my work within two minutes of opening the PR. Read the note, verify it, then fix it or schedule it. Don't treat it as a verdict on you.

Closing

The scariest part of my first contribution wasn't the Korean. It was pressing "Create pull request" on a repo with 9,000 stars.

Then it was over. One file. One afternoon. A maintainer I've never met merged it in less than an hour.

If you've noticed something broken in software you use, you're already qualified to fix it. Your perspective is the qualification. You noticed. Most people didn't, or didn't bother.

Call-to-Action

If you've been carrying a small fix around in your head, consider this your nudge: file the issue today. Not the PR. The issue.

And tell me in the comments: what's the fix you've noticed but never reported?

If you want more notes on open source, AI tooling, and building things in public, subscribe to the blog. New posts land there first.

Resources

• PR #1423 — docs: sync Korean README and polish translation
• Issue #1422 — sync Korean README with current English docs
• oh-my-opencode-slim on GitHub
• Earlier Korean README sync PRs: #502 (initial translation), #727, #935