Write Imperative Present Tense Sentences #36

New Issue

GiteaMirror · 2026-02-17T11:35:45-06:00

GiteaMirror commented

2026-02-17 11:35:45 -06:00

Originally created by @hutson on GitHub (Aug 19, 2018).

I would like to propose we establish the convention that all sentences in a commit message SHOULD be written in imperative present tense form.

Well-known examples of the imperative present tense form as a requirement:

cc @apetro @damianopetrungaro

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.

Originally created by @hutson on GitHub (Aug 19, 2018). I would like to propose we establish the convention that all sentences in a commit message SHOULD be written in imperative present tense form. Well-known examples of the imperative present tense form as a requirement: - https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html - https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#subject - https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project - https://medium.com/@danielfeelfine/commit-verbs-101-why-i-like-to-use-this-and-why-you-should-also-like-it-d3ed2689ef70 - https://chris.beams.io/posts/git-commit/ cc @apetro @damianopetrungaro --- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

GiteaMirror added the suggestion label 2026-02-17 11:35:45 -06:00

GiteaMirror closed this issue

2026-02-17 11:35:46 -06:00

GiteaMirror commented

2026-02-17 11:35:47 -06:00

@damianopetrungaro commented on GitHub (Aug 20, 2018):

I am totally fine with this!
I use this already as a best practice in all my commit messages, thanks to @apetro to point it out!

If someone wanna work on it for me it's fine.

@conventional-commits/committee what do you think about it?

@damianopetrungaro commented on GitHub (Aug 20, 2018): I am totally fine with this! I use this already as a best practice in all my commit messages, thanks to @apetro to point it out! If someone wanna work on it for me it's fine. @conventional-commits/committee what do you think about it?

GiteaMirror commented

2026-02-17 11:35:48 -06:00

@bcoe commented on GitHub (Aug 24, 2018):

I'm a -1 on this one. Even though it seems like this is probably a good habit to be in, I think it goes against the goal of our specification being as simple and flexible as possible if we start prescribing too many rules about how commit messages should be written. tldr; it adds a step without adding much value IMO.

Perhaps we could compromise and add this to the F.A.Q. section?

should I use the imperative preset tense?

several communities recommend this and it might be a practice worth using.

In our redesign @damianopetrungaro maybe we can make our F.A.Q. a bit better to read and link to?

unrelated, @hbetts perhaps we should all work together and make sure we're not deviating from RFC 2119, I'd like to fix this.

@bcoe commented on GitHub (Aug 24, 2018): I'm a -1 on this one. Even though it seems like this is probably a good habit to be in, I think it goes against the goal of our specification being as simple and flexible as possible if we start prescribing too many rules about how commit messages should be written. tldr; it adds a step without adding much value IMO. Perhaps we could compromise and add this to the F.A.Q. section? > should I use the imperative preset tense? > several communities recommend this and it might be a practice worth using. In our redesign @damianopetrungaro maybe we can make our F.A.Q. a bit better to read and link to? --- unrelated, @hbetts perhaps we should all work together and make sure we're not deviating from `RFC 2119`, I'd like to fix this.

GiteaMirror commented

2026-02-17 11:35:49 -06:00

@hutson commented on GitHub (Aug 24, 2018):

flexible as possible

Making a specification flexible seems like an antithesis of the goal of a specification.

it adds a step without adding much value IMO.

This is definitely how I feel we should be gauging the value of adding an item to the specification.

I'm somewhat on the fence about whether the value outweighs the extra step/recommendation.

I find that the imperative form ensures a commit message description clearly states the change made, which ultimately makes it easier to reason about what my expectations should be for a commit.

However, it's difficult to enforce and easy to not follow.

Perhaps we could compromise and add this to the F.A.Q. section?

I would be fine with that. Though, instead of adding a FAQ question for should I use the imperative preset tense?, maybe generalize it a little, like what writing form should I use?.

unrelated, @hbetts perhaps we should all work together and make sure we're not deviating from RFC 2119, I'd like to fix this.

What did you have in mind, and should we file a separate issue to carry on that discussion?

@hutson commented on GitHub (Aug 24, 2018): > flexible as possible Making a specification _flexible_ seems like an antithesis of the goal of a specification. > it adds a step without adding much value IMO. This is definitely how I feel we should be gauging the value of adding an item to the specification. I'm somewhat on the fence about whether the value outweighs the extra step/recommendation. I find that the _imperative_ form ensures a commit message description clearly states the change made, which ultimately makes it easier to reason about what my expectations should be for a commit. However, it's difficult to enforce and easy to not follow. > Perhaps we could compromise and add this to the F.A.Q. section? I would be fine with that. Though, instead of adding a FAQ question for `should I use the imperative preset tense?`, maybe generalize it a little, like `what writing form should I use?`. > unrelated, @hbetts perhaps we should all work together and make sure we're not deviating from RFC 2119, I'd like to fix this. What did you have in mind, and should we file a separate issue to carry on that discussion?

GiteaMirror commented

2026-02-17 11:35:49 -06:00

@bcoe commented on GitHub (Aug 24, 2018):

What did you have in mind, and should we file a separate issue to carry on that discussion?

Yeah let's start with separate issues, I appreciate the set of eyes, I bet we've drifted a bit from the RFC over time; I was fairly new to this when I hammered out the first draft with @jameswomack.

making a specification flexible seems like an antithesis of the goal of a specification.

Fair point, the very act of making a specification is pretty pedantic 😝My major goals drafting the original version of this was to:

have a central place to point to for the standard (the documentation was spread out over a few tools).
distill the standard into as few steps as possible, such that it's easy to communicate to engineers that it isn't hard to add to your workflow (this is why I dropped some other requirements of angular, e.g., continuing to allow alternative types).

tldr; I'm trying to be resistant towards having too many steps if we can avoid it, which was why I leaned towards the F.A.Q. here.

@bcoe commented on GitHub (Aug 24, 2018): > What did you have in mind, and should we file a separate issue to carry on that discussion? Yeah let's start with separate issues, I appreciate the set of eyes, I bet we've drifted a bit from the RFC over time; I was fairly new to this when I hammered out the first draft with @jameswomack. > making a specification flexible seems like an antithesis of the goal of a specification. Fair point, the very act of making a specification is pretty pedantic 😝My major goals drafting the original version of this was to: 1. have a central place to point to for the standard (the documentation was spread out over a few tools). 2. distill the standard into as few steps as possible, such that it's easy to communicate to engineers that it isn't hard to add to your workflow (this is why I dropped some other requirements of angular, e.g., continuing to allow alternative `type`s). tldr; I'm trying to be resistant towards having _too_ many steps if we can avoid it, which was why I leaned towards the F.A.Q. here.

GiteaMirror commented

2026-02-17 11:35:51 -06:00

@damianopetrungaro commented on GitHub (Aug 24, 2018):

@bcoe I agree with you and with @hbetts as well.

I think a good compromise would be using the FAQ and in the new UI I can do the section more relevant adding a link on the top of the page.

@damianopetrungaro commented on GitHub (Aug 24, 2018): @bcoe I agree with you and with @hbetts as well. I think a good compromise would be using the FAQ and in the new UI I can do the section more relevant adding a link on the top of the page.

GiteaMirror commented

2026-02-17 11:35:52 -06:00

@bcoe commented on GitHub (Feb 18, 2019):

I think we covered this in the FAQ \o/

@bcoe commented on GitHub (Feb 18, 2019): I think we covered this in the FAQ \o/

GiteaMirror referenced this issue

2026-02-17 11:56:08 -06:00

[PR #36] [MERGED] spelling: elements #255

Sign in to join this conversation.