Ask
23

Is it worth opening a pull request for a handful of typos in someone's README?

Reading through a repository I do not contribute to, I noticed a few small spelling mistakes in the README. Nothing that causes confusion, just typos.

I can see three options: open a pull request, open an issue describing them, or leave it alone. My worry is that a maintainer's review time is valuable and a trivial change still costs them a context switch, so a well-meant fix might be a net negative for them.

What do maintainers actually prefer here?

5 answers Share
Report

Answering anonymously — a moderator will review it first.

  • @maintainer_mika · last wk.

    Speaking as a maintainer: open the pull request, and your instinct about review cost is right but points the other way.

    A pull request fixing typos is one glance and one button. An issue saying "there are some typos in the README" is work I now have to do: find them, decide on each, edit, commit. The issue is more expensive for me than the fix.

    What makes it genuinely cheap to accept:

    • Batch them. One pull request with all the typos, not one per word.
    • Nothing but typos. Do not reformat, do not rewrap lines, do not switch quote styles. A diff with fifty changed lines because your editor reflowed the file is no longer a one-glance review.
    • A plain title. "Fix typos in README" tells me everything.
    • No explanation needed. The diff is the explanation.

    Do that and you have made the project better at essentially zero cost to anybody.

    29
    Share
    Reply

    Answering anonymously — a moderator will review it first.

    Report
  • @architect_ayla · last wk.

    There is a context worth knowing about because it has made some maintainers wary: during certain contribution campaigns, projects receive a flood of trivial pull requests from people chasing a participation count rather than trying to help.

    That produced a lot of low-value noise and some projects reacted by discouraging documentation-only changes entirely, or labelling them so they do not count.

    It does not mean your fix is unwelcome. It does mean that if you are opening it during one of those periods, a one-line note that you found this while reading the docs — that is, that you are a user rather than a collector — costs you nothing and reads very differently.

    19
    Share
    Reply

    Answering anonymously — a moderator will review it first.

    Report
  • @avionics_arto · last wk. · 2 replies

    One more reason to send it that has nothing to do with the typos: it is the cheapest possible way to learn a project's contribution process.

    You find out whether they use a contributor agreement, what their checks are, how fast they respond and how they review. If you later want to contribute something substantial, you have done all of that once already on a change where nothing was at stake.

    I have suggested exactly this to people nervous about their first contribution more times than I can count.

    13
    Share
    Reply

    Answering anonymously — a moderator will review it first.

    Report
    • @maintainer_mika · last wk.

      This is the real answer for anyone hesitating. A typo fix is a free rehearsal of the whole process.

      8
      Share
      Reply

      Answering anonymously — a moderator will review it first.

      Report
  • @ports_adapters_pia · last wk.

    Two cases where the answer changes, worth checking first:

    The project has a contributing guide that says otherwise. Some projects ask for an issue first, or have a policy about documentation changes. Thirty seconds of reading saves an awkward exchange.

    It is not actually a typo. Be careful with regional spelling differences, technical terms that look wrong but are not, deliberate stylisation of a product name, and text in a language you do not speak natively. "Correcting" British spelling to American, or a domain term to the ordinary word, is a small insult rather than a contribution.

    When I am unsure whether something is a typo or a choice, I leave it. The ones I am confident about are worth fixing and the ones I am not are worth nothing.

    24
    Share
    Reply

    Answering anonymously — a moderator will review it first.

    Report