-20

When I edit an answer, the help text for the "Edit summary" text input field reads:

Briefly explain your changes (corrected spelling, fixed grammar, improved formatting)

Most people seem to agree that for "commit messages" it's better practice to focus on what's the difference between the old and new versions, and not on the singular real-world action that was taken to make a specific version.

More concretely, use simple present-tense, imperative style, instead of past-tense.

In conclusion, the following might be a better help text:

Briefly explain your changes (correct spelling, fix grammar, improve formatting)

8
  • 4
    I do not see the relation between focus on what's the difference between the old and new versions and the change to present tense. Can you elaborate? (For what it's worth, I always use past tense for my commit messages, and I would find using present tense quite awkward.) Jul 11, 2016 at 14:33
  • 2
    Also, edit summaries aren't VCS commit messages
    – jonrsharpe
    Jul 11, 2016 at 15:09
  • @FrédéricHamidi: corrected spelling in my mind places the focus on what the author of the patch did when he created the patch, and transitively also on the author. On the other hand correct spelling doesn't have that unnecessary focus. That's presumably the reason why the widely preferred Git commit message style is imperative, present-tense. Do a google search! Your preference is of course valid but most people don't seem to share it.
    – Jo So
    Jul 11, 2016 at 16:14
  • 1
    @jonrsharpe: That's a truism. But what are the relevant differences? Why wouldn't the same arguments apply for edit summaries?
    – Jo So
    Jul 11, 2016 at 16:16
  • 3
    @JoSo, okay, I did find this but I have to say that I disagree -- to me imperative, present tense conveys a task, not its result; it describes what we have to do, not what we have done. YMMV, though, but it sure looks strange to me. Jul 11, 2016 at 16:18
  • @FrédéricHamidi: Somebody on that page also argues for the simple present-tense from the standpoint of looking for a suitable commit to apply. It doesn't apply to the same extent to edit summaries, though.
    – Jo So
    Jul 11, 2016 at 16:26
  • 1
    Whether you tell people to use present tense or past tense in the edit summary, they will still write "fixed grammer" or "formatting" for every...single...edit, even though all they do is add code formatting to random words and change "thx in advance" to "thanks in advanced!" Jul 11, 2016 at 16:34
  • 3
    @JoSo primarily because you can't cherry-pick an edit as you can with a commit. FWIW I like "corrects spelling" vs. "correct spelling" and "corrected spelling" for commits, but the latter for edits.
    – jonrsharpe
    Jul 11, 2016 at 16:36

1 Answer 1

6

I prefer how it is, which I feel is more intuitive. The way I see it, when you see "fixed spelling" on a revision, it reads like "this revision fixed [the] spelling".

Quite realistically, I mostly stopped leaving edit summaries since I got 2k rep (most of the time it's obvious what I fixed). But I did gain some insight into what makes a good edit summary from reviewing edits:

The verb is the least important part.

"Improve formatting" is no better or worse than "improved formatting" or "... formatting ..."

I would much prefer that the edit summary describe what was fixed, even if it is just a list (with or without verbs): "grammar; fixed link; OP's code from comments."

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .