English for Open Source: PRs, Issues, Community Etiquette, and Documentation

Open source contribution is one of the fastest ways to improve your English for software development. Every pull request you open, every issue you file, and every code review comment you write is read by native and non-native speakers from around the world. Getting the language right matters: a well-written PR gets merged faster; a clearly written bug report gets fixed sooner. This guide covers the vocabulary and conventions for every stage of open source participation.

Pull Request Language

A pull request (PR) is your proposal to integrate your changes into a codebase. The PR description is one of the most important pieces of writing a developer produces.

Pull request / PR — a request to merge a branch of changes into the main codebase. In some tools (notably GitLab) it is called a merge request (MR). “I opened a PR for the bug fix — it’s ready for review.”

Draft PR / WIP PR — a pull request marked as not ready for review yet, used to share work in progress and get early feedback. “I opened it as a draft so you can see the direction before I finish the implementation.”

Changeset / diff — the set of code changes in a pull request. “The changeset is small — just two files changed.”

Reviewers — the people assigned to review the PR. “Can you add @sofia and @tomas as reviewers? They own that module.”

Request changes — a review outcome where the reviewer requires modifications before approval. “The reviewer requested changes on my PR — mainly around error handling.”

Approve — formally marking a PR as acceptable for merging. “Once you have two approvals, go ahead and merge.”

Squash and merge — a merge strategy that combines all commits in a PR into a single commit on the main branch. “We squash and merge all PRs to keep the commit history clean.”

Rebase — reapplying your commits on top of the latest state of the base branch. “Please rebase your branch before merging — there are conflicts with main.”

Writing a Good PR Description

A well-written PR description answers: What does this change? Why was this change needed? How was it tested?

A typical structure:

What: Adds retry logic to the payment API client. Why: The payment provider occasionally returns transient 503 errors that succeed on retry. Previously, these caused unnecessary order failures. How tested: Added unit tests for the retry logic. Tested manually against the staging environment. Notes: The max retry count is configurable via PAYMENT_MAX_RETRIES env var (default: 3).

Issue Filing Vocabulary

Filing a clear bug report or feature request is a skill. Good issues get attention; vague issues get ignored.

Bug report — a description of unintended behaviour in the software. A good bug report includes: steps to reproduce, expected behaviour, actual behaviour, and environment details. “I filed a bug report with a minimal reproduction case.”

Feature request — a proposal for new functionality. “I opened a feature request to add export-to-CSV to the dashboard.”

Steps to reproduce (STR) — a numbered list of actions that reliably trigger the bug. “STR: 1. Log in. 2. Navigate to /settings. 3. Click ‘Delete account’. 4. Observe 500 error.”

Expected behaviour — what the software should do. “Expected: the account is deleted and the user is redirected to the home page.”

Actual behaviour — what the software actually does. “Actual: a 500 Internal Server Error is returned and the account is not deleted.”

Minimal reproduction case / minimal repro — the smallest possible piece of code or sequence of steps that reliably reproduces the bug. Maintainers value these highly. “I created a minimal repro in a CodeSandbox — link in the issue.”

Triage — the process by which maintainers assess and categorise new issues. “The issue has been triaged and labelled bug/confirmed — it’s in the backlog.”

Stale issue — an issue with no recent activity, often automatically labelled and closed by bots. “The issue was closed as stale after 90 days of inactivity.”

Community Etiquette Vocabulary

Open source communities have norms that are mostly unwritten but widely understood. Knowing them helps you participate respectfully and effectively.

Code of Conduct (CoC) — a document that specifies the standards of behaviour expected in a community. Most major projects have one. “Please review the Code of Conduct before contributing.”

LGTM — “Looks Good To Me” — approval on a code review. “LGTM, great work!”

NIT / nit — short for “nitpick” — a minor, optional suggestion in a code review that does not block the PR. “NIT: could rename this variable to make its purpose clearer, but it’s not a blocker.”

Blocking comment — a review comment that must be addressed before the PR can be merged, as opposed to a suggestion or nit.

Good first issue — a label used to mark issues suitable for new contributors. “I picked up a good first issue to get familiar with the codebase.”

Upstream — the original open source project from which you forked. “I’ll upstream this fix once it’s been tested in our fork.”

Fork — a personal copy of a repository that you can modify without affecting the original. “Fork the repo, make your changes on a branch, then open a PR from your fork.”

CONTRIBUTING.md — a file in the repository that explains how to contribute: coding standards, branch naming conventions, commit message format, and PR process. “Read the CONTRIBUTING.md before opening a PR — it explains the commit message format.”

Ping — to mention someone to draw their attention. “I’ll ping the maintainer to check if this PR is still on their radar.”

Documentation Language

Writing documentation is a core part of open source contribution, and clear English is essential.

README — the first document a visitor to a repository reads. It should explain what the project does, how to install it, and how to use it. “The README needs a usage example — new users won’t know where to start.”

Docstring / JSDoc / TSDoc — inline documentation attached to a function, class, or module. “Every public function must have a JSDoc comment explaining its parameters and return value.”

Changelog — a document listing changes made in each version of the software, often in reverse chronological order. “Don’t forget to add an entry to the CHANGELOG for user-facing changes.”

API reference — comprehensive documentation of every public function, class, and configuration option. “The API reference is auto-generated from TSDoc comments.”

Example / usage example — a short, working code snippet demonstrating how to use a feature. Examples are often the most-read part of documentation. “The feature is there but undocumented — can you add a usage example to the README?”

Practical Exercises

PR description practice: Choose any recent code change you made (even a personal project). Write a PR description following the What / Why / How tested structure.
Bug report drill: Find a bug in any open source tool you use. Write a bug report with STR, expected behaviour, actual behaviour, and environment details. (You do not need to file it — the exercise is in the writing.)
Code review comment rewrite: Take a blunt review comment (“This is wrong”) and rewrite it as a constructive, specific suggestion that a maintainer would be happy to receive.
README audit: Find an open source project with a poor README. Identify three specific improvements and write a better version of one section.

Practise the vocabulary from this post in the Writing exercises and Git vocabulary exercises on Coders Lingo.