🔀 Reading: CONTRIBUTING.md

Small, focused PRs: the gold standard in open source and professional engineering

The rule "one logical change per PR" exists for several deeply practical reasons:

1. Reviewer cognitive load: Reviewing code is mentally demanding. A PR with 15 changed files spanning a new feature, a bug fix, and a refactor forces reviewers to context-switch constantly. A 200-line single-purpose PR can be thoroughly reviewed in 15 minutes. A 1,200-line mixed PR may take hours — and reviewers are more likely to approve without truly understanding it.

2. Bisect-ability: If a bug appears after merging a large PR, narrowing down which change introduced the bug is much harder. Small, focused commits and PRs mean each merge has a clear, attributable purpose — making git bisect and rollbacks far more effective.

3. Faster iteration: A focused PR that's mergeable now is better than a complete feature in one massive PR that sits in review for three weeks. Splitting work into logical chunks keeps the project moving.

4. Easier conflict resolution: When multiple contributors work in the same codebase, large PRs are more likely to touch the same files as others' in-progress work, creating painful merge conflicts.

What "one logical change" means in practice:

• Refactoring + feature → two PRs (refactor first, then feature on top)
• Bug fix + unrelated cleanup → two PRs
• Feature implementation → could be one PR, or a sequence (data model, then API layer, then UI)

For open source specifically: Maintainers are often volunteers. Respecting their time with small, reviewable PRs is a courtesy — and it gets your code merged faster.

Why "closed" issues are as important as open ones

On GitHub, issues can be closed for several distinct reasons — and each has different implications for a new contributor:

Closed as "completed": The bug was fixed or the feature was implemented. The fix may already be in a release you haven't updated to — check the linked PR and the version. Opening a duplicate wastes maintainer time if your problem is already solved.

Closed as "won't fix": The maintainers deliberately declined to address this. Maybe it's out of scope, conflicts with project direction, or requires a design change they're not willing to make. Opening a new issue about the same thing without new arguments is disrespectful of that decision.

Closed as "duplicate": Already tracked elsewhere. The original tracking issue is linked in the close comment — follow that instead.

Closed as "invalid" or "not a bug": Previous investigation showed this is a user error or expected behaviour. Reading this saves you from opening a report that'll be closed with the same explanation.

Closed as "stale": The issue was inactive and auto-closed. If the problem persists, you can comment on the original and potentially reopen it (with new information) rather than creating a duplicate.

Professional English skill: When you search and find a relevant closed issue, the correct approach is to either:

• Comment on the closed issue with new information ("This is still reproducible on v3.2.1 — I've attached a minimal reproduction") — maintainers can reopen it
• Open a new issue explicitly referencing the closed one: "This appears related to #342 (closed) but persists in v3.2.1 because..."

This demonstrates that you've done your homework and respects the community's history.

Open source licensing: what CLA-lite clauses actually mean

This clause is a simplified form of a Contributor Licence Agreement (CLA). It's common in open source projects to include it directly in the CONTRIBUTING.md rather than requiring a formal signed document.

What MIT licence means for your contribution: The MIT licence is one of the most permissive open source licences. By agreeing to this clause, you grant:

• Anyone (not just the project maintainers) the right to use, copy, modify, merge, publish, distribute, sublicense, and sell your contributed code
• This right is perpetual and irrevocable — you cannot later decide to take your contribution back

What you do NOT give up:

• Your copyright — you remain the author. The commit log records your authorship permanently.
• The right to use your own code in other projects — MIT doesn't require exclusivity
• The right to release the same code under different licences for other uses (dual licensing)

Why projects include this: Without explicit licence grant, the legal status of contributions is ambiguous. If a contributor later claims their code was used without permission, the project could face legal action. This clause prevents that by establishing a clear licence at the moment of contribution.

Full CLAs vs. CONTRIBUTING.md clauses: Large companies (Google, Facebook, Apache Foundation) use formal CLAs requiring a digital signature. Smaller projects use CONTRIBUTING.md clauses as a lower-friction alternative. Both serve the same legal purpose: ensuring the project can distribute and modify all contributed code.

Vocabulary note: "sublicense" means the project can grant others the same rights — so if a company uses this library, they can also distribute it under MIT without asking the original author.