DEV Community

IndieHacker
IndieHacker

Posted on

How to Write a PR Description That Sounds Native

#career #github #softwareengineering #writing

How to Write a PR Description That Actually Sounds Native

I've reviewed thousands of PRs from developers across 6 countries. The code is usually fine. The English? That's where things get interesting.

Here's a collection of real patterns I've seen (anonymized), what native speakers actually think when they read them, and how to fix each one.

The "Please Kindly" Pattern

What non-native speakers write:

Please kindly review this PR. I have made some changes to the authentication module. 
Please let me know if you have any questions. Thank you for your time.
Enter fullscreen mode Exit fullscreen mode

What native speakers think: "This reads like a customer service email, not a PR description."

What to write instead:

## What
Refactored the auth module to use JWT refresh tokens.

## Why
Session tokens were expiring mid-workflow (see #142). Refresh tokens let us extend sessions without re-auth.

## How
- Added `refreshToken()` to AuthService
- Updated middleware to auto-refresh on 401
- Migration: new `refresh_tokens` table
Enter fullscreen mode Exit fullscreen mode

The rule: PR descriptions are technical documents, not letters. Use What/Why/How structure. Skip greetings and pleasantries.

The "I Think Maybe" Pattern

What non-native speakers write:

I think maybe we should consider possibly using a different approach here, 
if that's okay with you.
Enter fullscreen mode Exit fullscreen mode

What native speakers think: "Are they unsure about the technical approach, or just being overly polite? I genuinely can't tell."

What to write instead:

I'd suggest using a connection pool here instead of creating new connections per request. 
The current approach will hit scalability issues around ~100 concurrent users.
Enter fullscreen mode Exit fullscreen mode

The rule: One hedge word is polite. Three hedge words is confusing. "I'd suggest" or "Consider" is enough — then state your case directly.

The "You Should" Pattern

What non-native speakers write:

You should change this variable name. You should also add error handling here. 
You should not use var.
Enter fullscreen mode Exit fullscreen mode

What native speakers think: "This feels like a lecture, not a code review."

What to write instead:

Severity Template Example
Nitpick Nit: [suggestion] Nit: userCount reads better than cnt
Suggestion Consider [doing X] — [reason] Consider extracting this into a helper — it's used in 3 places
Blocking [Issue]: [explanation] This will panic on nil input — we need a guard here

The rule: Frame feedback as observations about the code, not instructions to the person. "This will panic" vs "You should add a nil check."

The "Fixed Bug" Commit Message

What non-native speakers write:

fixed bug
update code
modify function
add some changes
Enter fullscreen mode Exit fullscreen mode

What native speakers think: "What bug? What code? I'm going to have to read the entire diff."

What to write instead (Conventional Commits):

fix(auth): prevent session expiry during active requests

The JWT middleware was checking token expiry before processing the request,
causing 401s for long-running uploads. Now checks after.

Closes #142
Enter fullscreen mode Exit fullscreen mode

The template:

<type>(<scope>): <what changed>

<why it changed — the context that the diff alone doesn't show>

<reference to issue/ticket>
Enter fullscreen mode Exit fullscreen mode

Types: feat, fix, refactor, docs, test, chore

The "Please Help Me" Standup

What non-native speakers write:

Yesterday I was working on the task. Today I will continue working on it. 
I have no blockers.
Enter fullscreen mode Exit fullscreen mode

What native speakers think: "This tells me nothing."

What to write instead:

**Yesterday:** Got the JWT refresh flow working end-to-end. Tests passing locally.
**Today:** Integration testing against staging, then PR.
**Blocked:** Need access to the staging KV namespace — @ops can you add me?
Enter fullscreen mode Exit fullscreen mode

The rule: Be specific. Name the feature, the status, the next concrete action. "Working on the task" is a non-update.

The Cheat Sheet

Instead of... Write...
Please kindly... (just skip it)
I think maybe we should consider... I'd suggest... / Consider...
You should... Nit: / Consider... / This will [problem]
Fixed bug fix(scope): description
I was working on the task Got [specific thing] working, next up [specific thing]
Please let me know if you have any questions (just skip it — they'll ask if they have questions)
Thank you for your time (unnecessary in PR context)
I want to ask... Quick question: ...
Can I know...? Do you know...? / Is there a way to...?
I have met a problem I ran into an issue with...

Why This Matters

These aren't grammar mistakes. They're register mistakes — using email-formal language in a casual-technical context, or using a command tone when a suggestion tone is expected.

Native speakers won't correct you. They'll just form a vague impression that your communication is "a bit off." Over time, that impression compounds.

The good news: the patterns are finite and learnable. Once you internalize the ~20 templates above, you'll sound native in 90% of dev communication.

I built DevGlish to solve this exact problem. It's a macOS menu bar app that gives you context-aware English suggestions while you work — select text, press ⌘⇧D, get instant guidance on pronunciation, phrasing, and native speaker conventions. It even detects which app you're in (Slack vs GitHub vs email) and adjusts the tone.

Free tier: 10 lookups/day. Try it →

Top comments (0)