Should I submit a pull request to correct minor typos in a Readme file?

Question

While going through the README file of a GitHub repository I am not a contributor of, I noticed a few minor typos and wondered if I should submit a pull request to correct them or if reviewing the request would take the maintainer too much time to be worth it. I considered the three courses of action:

1. Correct the typos and submit a pull request with the position of each correction in the summary field.
2. Send the maintainer an email with the proposed corrections.
3. Do nothing.

Which of these (or any other) options is most appropriate?

To give some context, the repository is actively maintained and has about 10 contributors. The typos I have noticed do not make the README misleading nor ambiguous. I have used GitHub for some time for small personal projects, but have little experience with pull requests and how much time and efforts they take to review (hence my question).

Answer 1

Just fix all the typos you noticed and create a pull request with a comment along the lines of 'Fix typos'. Then it's one button to click for a person with the correct access.

You don't need to explain each and every typo; it will be clear in the diff itself.

Getting information about the typos from the e-mail will be harder to apply for the developers (and may be even harder for you).

Answer 2

Some context that may or may not be relevant.

A cloud hosting provider named DigitalOcean hosts an event every year called Hacktoberfest to encourage people to contribute to open source projects in exchange for a T-shirt. Wonderful as it is to encourage more people to get into open source, offering a reward in return for gameable metrics and packing it all into one month resulted in many projects receiving a flood of low-quality pull requests that were perceived by some maintainers as spam. A number of these involved trivial changes or vandalism to README files, some inspired by a demonstration on a YouTube channel.

At worst, we're talking about things like this "improve docs" PR, which only added unnecessary periods to comments, or this one, which added an odd and unnecessary header to a README. It was particularly noticeable this year, with some projects receiving a dozen of these in the first day of the event, which caused a lot of consternation among project maintainers and blog posts like DigitalOcean's Hacktoberfest is Hurting Open Source.

Hacktoberfest is over, and that specific problem has abated (the amount of spam caused them to change the way the program worked after a few days to make it opt-in for project maintainers), at least until next year, but that incident gives a bit of context into how many maintainers think about pull requests: PRs exist to improve the software, and PRs that seem to exist just for the sake of changing something without a clear purpose or benefit may be frowned upon, especially in bulk. If you were only fixing a typo in a comment, seemed to be changing documentation for no real reason, or arbitrarily rewriting a bit of code without making any particular improvement, that's the sort of thing that could raise eyebrows.

But in your case, your PR seems like it would genuinely improve the software. Having multiple typos in a README, assuming they are real typos and not regional spelling differences, is less than ideal, and you're providing a material improvement by fixing them.

The fact that you're asking this question and are concerned with respecting the maintainer's time makes it clear that your intentions are noble. Ultimately, to assuage your concerns, reviewing and merging a simple pull request is a quite quick and painless operation for a maintainer—look at the diff and click a button.

Lastly, GitHub is fundamentally just humans talking to each other. It's completely ok to write something like "This is my first pull request. I hope this is useful, but no worries if it's not" or something to that effect if you're unsure.

Answer 3

1. Correct the typos and submit a pull request with the position of each correction in the summary field.

That information is already visible when looking at the changes themselves, and any pull request reviewer is obviously going to be looking at the changes that were made.

The summary field should be kept for a human-readable short summation of what this PR contains. In your particular case, "fixed some typos" accurately sums it up.

2. Send the maintainer an email with the proposed corrections.

The entire point of GitHub is that you can cooperatively coordinate changes to source code. If emailing someone and having them make the changes were the way to go, GitHub (and versioning systems in general) would lose their primary purpose.

Whether you corrected a typo or changed some code is irrelevant as to how GitHub works and how its members coordinate changes they've made.

The only reason why I'd consider email the maintainer was to clarify something, e.g. if you're unsure if something is unintended behavior or not.

In this case, a simple PR for typo fixes doesn't really need clarification, the maintainer can look at the PR itself and decide whether they need to or not. You'd spend more time trying to get them to look at everything and asking if your correction is correct, than you would opening the PR itself.

Just doing the PR directly saves both you and them some time and effort.

3. Do nothing.

I mean, it's technically an option, but it doesn't quite address the question on how you should approach this. The inherent implication of such a question is that you're trying to do the thing you're asking about. Doing nothing is not doing something.

Answer 4

Not that this specifically answers the question, as there are already answers, but here is the general advise I give people on commits and messages.

Break up commits into logical chunks. The example I use for this is if a file you need to edit has a bunch of formatting issues. You should make one commit to correct the formatting, then a second commit to fix the logic that you originally went to the file for. This way, if for some reason the logic needs to be reverted, the white space changes can stay in for the next person that needs to go in there. Ideally the formatting you fix meets whatever the local coding standard is.

As far as an individual commit, answer the questions that they were taught when writing grade school papers. Who? What? When? Where? Why? How?

Who is generally answered by the author of the commit.

When is the timestamp of the commit

What and where are generally the diff of the commit.

Why and how really need to be in the commit message. To me, this is the most important part to get right and hard for a lot of software engineers to do. In this case specifically, and since the changes are minor, how is irrelevant and why is just that you fixed typos.

TLDR; Don't worry about a commit to fix typos or formatting. Make a commit and put it out for review.

Answer 5

The other answers are good, but first check if there are any instructions for contributing - in particular regarding signing a CLA. (I see that @eckes also stated this as a comment on the original question.)

If the CLA process seems too complicated it might be better to open an issue (or send an e-mail) only stating the spelling mistakes than to construct a PR.