How to Write Better GitHub Pull Requests on Mac

PR descriptions are read by reviewers who need enough context to review confidently. Poor writing in a PR slows the review cycle, forces clarifying questions, and signals carelessness about the work being submitted. PR descriptions with clear structure get reviewed approximately 40% faster than unstructured descriptions, according to GitHub's 2024 engineering survey. The setup below covers both the writing habits and the tools that make them easier to maintain.

Why does PR writing quality matter?

A pull request is a communication artifact as much as a code change. The reviewer comes to it cold - they did not write the code, they may not know the specific issue being addressed, and they have limited time. A good PR description gives them everything they need in a scannable structure: what changed, why it was needed, how it was implemented, and how it was tested.

An unclear PR description creates a queue of clarifying questions. Each question requires a context switch from the author and a wait for the reviewer. The review cycle stretches. For teams with many PRs in flight simultaneously, poor PR writing compounds into measurable delays across the sprint.

Spelling and grammar errors in PR descriptions are also worth addressing. They signal different levels of care to different reviewers. Some reviewers do not care. Others interpret a sloppily-written description as a signal about the quality of the underlying code. Whether or not that correlation is fair, it is a real dynamic in code review culture.

How do you set up tools for better PR writing on Mac?

Step 1: Install Charm for correction in GitHub's web UI. macOS autocorrect does not work in browser-based text fields - it only works in native Mac apps. GitHub runs in the browser, so PR title and description fields have no autocorrect by default. Charm reaches those fields through the macOS Accessibility API, providing real-time spelling correction (Spells, cyan glow) and grammar correction (Polish, blue glow) while you type on github.com.

Step 2: Write PR titles as imperative sentences. This is a convention that mirrors good commit message style and produces the clearest titles: "Add retry logic for API calls", not "Added retry logic" or "Adding retry logic". The imperative form describes what the PR does when merged. It reads naturally when scanning a list of PRs: you see what each one does rather than what its author was doing.

Step 3: Structure descriptions with a four-section template. The most consistently effective PR description structure is: What (what specifically changed in this PR), Why (the motivation - what problem is solved or what requirement is met), How (the implementation approach, especially any non-obvious choices), and Test plan (how the change was verified and what a reviewer should do to test it themselves). Not every PR needs all four sections in detail, but having the structure available prevents the most common omissions.

Step 4: Add technical terms to your personal dictionary. PR descriptions contain function names, library names, framework terms, and domain vocabulary that no general spell checker knows. Charm flags "APIClient" or "parseWebhookPayload" as errors because they are not in any dictionary. Adding your codebase's specific vocabulary to your Charm personal dictionary (Charm preferences > Personal Dictionary) takes a few minutes and permanently prevents these false corrections.

Step 5: Use Oracle for PR boilerplate. Charm's Oracle word prediction (purple glow, Tab to accept) learns repeated phrases from your writing. PR descriptions have predictable opening patterns: "This PR adds...", "Fixes #...", "Closes the issue by...", "Tested by running..." and "No breaking changes." Oracle recognises these quickly and offers completions that reduce the keystrokes needed for the structural parts of the description.

Step 6: Read your description as a reviewer before opening. Before clicking "Create Pull Request", reread your description imagining you are a reviewer who knows the codebase but not the specific change or its context. If your description requires a follow-up question to review, add the missing context now. This one habit saves more back-and-forth than any tool.

Step 7: Link to issues rather than duplicating context. If the relevant GitHub issue contains good background context on the problem, link to it with "Fixes #123" or "Closes #123" rather than repeating the same information in the PR description. The link automatically closes the issue when the PR merges. Avoiding duplication keeps the PR description focused on what is new rather than repeating what the issue already explains.

Frequently asked questions

How do I write better PR descriptions?

Use a four-section structure: What, Why, How, and Test plan. Write titles as imperative sentences. Install Charm for real-time correction in GitHub's browser-based text fields. Read your description as a reviewer before opening the PR. PRs with clear structure get reviewed approximately 40% faster than unstructured ones.

Does autocorrect work in GitHub?

macOS autocorrect does not work in GitHub because it only reaches native Mac apps, not browser text fields. Charm does work in GitHub's web UI - it uses the Accessibility API to provide real-time spelling and grammar correction in the PR title and description fields on github.com.

What makes a good pull request description?

A good PR description gives reviewers enough context to review without asking clarifying questions. It covers what changed, why it was needed, how it was implemented, and how it was tested. The title is imperative, the description is structured, and relevant issues are linked rather than duplicated.

Can Charm help with GitHub writing?

Yes. Charm works in GitHub's web UI through the Accessibility API. It provides real-time spelling and grammar correction while you type PR titles and descriptions. Oracle also works for word prediction in PR descriptions, useful for common boilerplate phrases that appear across many PRs.

How do I improve my code review communication?

Write PR descriptions that make the reviewer's job easier: clear four-section structure, imperative titles, and sufficient context. Add codebase-specific vocabulary to your Charm personal dictionary. Read each PR description as a reviewer before opening it. Link to issues rather than duplicating context.