change commit message format to present tense?

[Tim Graham]

A few contributors indicated in #django-dev that it could be beneficial to change our commit message format to match git's guidelines of present tense (instead of our current past tense convention) as it would be one less thing to remember when contributing to Django. Besides consistency with the current history, do you feel there are any benefits in continuing to use past tense instead of present tense?

[Carl Meyer]

I was one of those contributors in #django-dev. Not only are past-tense
commit messages non-standard for git (meaning they are one more thing a
new contributor is likely to trip over), I also personally find them
harder to write and make clear. Sometimes in a commit message you need
to reference past (pre-commit) behavior and make it clear how the commit
changes that behavior. I occasionally find that harder to do clearly
when the entire commit message is supposed to worded in the past tense.

So I find all the advantages (except for consistency with past history)
in favor of switching to the imperative mood.

Carl

[Jacob Kaplan-Moss]

I'm not entirely sure because my memory sucks, but odds are that I started the current standard of using past-tense. 

FWIW I no longer care even at all, I think as long as commit messages are clear we I don't care what tense they are. Following the standard git way seems totally OK to me.

Jacob 

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/576D6702.3080501%40oddbird.net.

For more options, visit https://groups.google.com/d/optout.

[Markus Holtermann]

I don't mind either way. If everybody seems to use present tense these
days, yeah, let's do that as well. As long as the general style of the
commit messages stays: Fixes|Refs #12345 -- Make it work

My 2¢

/Markus

>To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAK8PqJESDrr05-1jJeTbz8UQ%3D%2BJXYHU88w1iGBBnby5czwwVSA%40mail.gmail.com.

[Tobias McNulty]

I'm in support of this as well. Is the suggestion to change the format to:

A) Fixes #12345 -- Add support for ... / Validate that .... / etc.

OR

B) Fixes #12345 -- Adds support for ... / Validates that ... / etc.

OR

C) Something else?

I assume (A) but others may interpret this differently?

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/20160624172521.GF12981%40inel.local.

For more options, visit https://groups.google.com/d/optout.

--

Tobias McNulty
Chief Executive Officer

tob...@caktusgroup.com
www.caktusgroup.com

[Carl Meyer]

To be clear, the recommended git style is not present tense, it is
imperative mood. So it should _not_ be "Fixes #12345 -- Regulates the
frobnicator", it should be "Fix #12345 -- Regulate the frobnicator."

Carl

> <mailto:django-developers%2Bunsu...@googlegroups.com>.

> To post to this group, send email to
> django-d...@googlegroups.com

> <mailto:django-d...@googlegroups.com>.

> Visit this group at
> https://groups.google.com/group/django-developers.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/django-developers/576D6702.3080501%40oddbird.net
> .
> For more options, visit https://groups.google.com/d/optout.
>
>
> --
> You received this message because you are subscribed to the
> Google Groups "Django developers (Contributions to Django
> itself)" group.
> To unsubscribe from this group and stop receiving emails from
> it, send an email to
> django-develop...@googlegroups.com

> <mailto:django-developers%2Bunsu...@googlegroups.com>.

> To post to this group, send email to
> django-d...@googlegroups.com

> <mailto:django-d...@googlegroups.com>.

> Visit this group at
> https://groups.google.com/group/django-developers.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/django-developers/CAK8PqJESDrr05-1jJeTbz8UQ%3D%2BJXYHU88w1iGBBnby5czwwVSA%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.
>
>
> --
> You received this message because you are subscribed to the Google
> Groups "Django developers (Contributions to Django itself)" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to django-develop...@googlegroups.com

> <mailto:django-developers%2Bunsu...@googlegroups.com>.

> To post to this group, send email to
> django-d...@googlegroups.com

> <mailto:django-d...@googlegroups.com>.

> Visit this group at https://groups.google.com/group/django-developers.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/django-developers/20160624172521.GF12981%40inel.local.
>
> For more options, visit https://groups.google.com/d/optout.
>
>
>
>
> --
>

> *Tobias McNulty
> *Chief Executive Officer
>
> tob...@caktusgroup.com <mailto:tob...@caktusgroup.com>
> www.caktusgroup.com <http://www.caktusgroup.com/>

>
> --
> You received this message because you are subscribed to the Google
> Groups "Django developers (Contributions to Django itself)" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to django-develop...@googlegroups.com

> <mailto:django-develop...@googlegroups.com>.

> To post to this group, send email to django-d...@googlegroups.com

> <mailto:django-d...@googlegroups.com>.

> Visit this group at https://groups.google.com/group/django-developers.
> To view this discussion on the web visit

> https://groups.google.com/d/msgid/django-developers/CAMGFDKQGyJPe%2BnNcsjusPZeMEquPGnobdhp_0pjxXEoJrWtqPQ%40mail.gmail.com
> <https://groups.google.com/d/msgid/django-developers/CAMGFDKQGyJPe%2BnNcsjusPZeMEquPGnobdhp_0pjxXEoJrWtqPQ%40mail.gmail.com?utm_medium=email&utm_source=footer>.

[Jon Dufresne]

On Fri, Jun 24, 2016 at 10:48 AM, Carl Meyer <ca...@oddbird.net> wrote:

To be clear, the recommended git style is not present tense, it is
imperative mood. So it should _not_ be "Fixes #12345 -- Regulates the
frobnicator", it should be "Fix #12345 -- Regulate the frobnicator."

Do you have a link to an authoritative source stating this as the recommended style or is it just common knowledge?

I'm not arguing against the proposal (in fact, I agree with it), I'm just curious if there is documentation to support one style over the other.

 

Cheers,

Jon

[Marc Tamlyn]

This post by Tim Pope is considered the "definitive guide to commit messages" as far as I'm aware.

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

+1 to adopting this style.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.

To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.

Visit this group at https://groups.google.com/group/django-developers.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CADhq2b4zz8Dd8%3Dh7PSuMvFOFok3Tn-K0JsQkVkNNiBKphkBH%2Bg%40mail.gmail.com.

[Daniele Procida]

Lately I keep being recommended <http://chris.beams.io/posts/git-commit/>.

The most compelling reason is that Git itself uses the imperative mood:

Merge branch ...

Revert ...

Daniele

[Carl Meyer]

The style that is most commonly recommended is described in the most
detail (with reasoning) in these blog posts:

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
http://chris.beams.io/posts/git-commit/

That same style is recommended in the Git Book in
https://git-scm.com/book/ch5-2.html

It is "endorsed" by git itself in that git uses the imperative mood when
it generates a commit message (e.g. for a merge) -- it generates "Merge
branch foo" not "Merges branch foo" or "Merged branch foo."

Also the git project's own commit messages use this style.

Carl

[Aymeric Augustin]

> On 24 Jun 2016, at 20:23, Carl Meyer <ca...@oddbird.net> wrote:
>
> The style that is most commonly recommended is described in the most
> detail (with reasoning) in these blog posts:
>
> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
> http://chris.beams.io/posts/git-commit/

Yes, let’s do that.

Django is the only project I’m aware of that uses the past tense convention.
Keeping doing it differently from everyone else is a sunk cost fallacy.

Also every letter we save is a win when trying to fit in the hilariously short
first line of every commit message.

--
Aymeric.

[Tim Graham]

With the idea of saving characters in the first line, would "Fix #XXX: Message" be better than ""Fix #XXX -- Message" also? This saves two characters without any loss of readability as far as I see.

[Carl Meyer]

On 06/24/2016 03:04 PM, Tim Graham wrote:
> With the idea of saving characters in the first line, would "Fix #XXX:
> Message" be better than ""Fix #XXX -- Message" also? This saves two
> characters without any loss of readability as far as I see.

Seems reasonable to me.

Carl

[Aymeric Augustin]

+0

--
Aymeric.

[Reinout van Rees]

Op 24-06-16 om 19:48 schreef Carl Meyer:

> To be clear, the recommended git style is not present tense, it is
> imperative mood. So it should _not_ be "Fixes #12345 -- Regulates the
> frobnicator", it should be "Fix #12345 -- Regulate the frobnicator."

Everybody seems to be in favour. I'll allow myself a small question mark
anyway.

Why? Well, django is well-known for its excellent documentation. Take
for instance the release notes. Here's a snippet:

"Django now offers password validation to help prevent the usage of weak
passwords by users."

That is how we communicate with our users.

Now back to commit messages and code. Code should be written for humans
reading it, not for computers executing it, right? Readability counts.
Now if I read the history of a file I'd expect to read something that's
pretty readable to me as a developer. I expect to read what happened:

"Added password validation to help prevent the usage of..."


Instead I'll now see commit messages like this:

"Add password validation to prevent the usage of..."

Linguistically, I'm getting an imperative order to do something. And I
have to translate it to a sentence that actually makes sense. Every
django programmer has to make that mental switch/translation.

Is that a cost we want to pay? Does it fit in with our tradition of
providing good documentation? Are we taking linguistic advise from the
people who brought us git's user interface instead of from our English
teachers?

We don't have to order git to do something, we have to communicate what
we've done to fellow programmers.



I'm not a native English speaker, so I might be missing some nuances.
Perhaps it is less weird if you're a native speaker.

Reinout

--
Reinout van Rees http://reinout.vanrees.org/
rei...@vanrees.org http://www.nelen-schuurmans.nl/
"Learning history by destroying artifacts is a time-honored atrocity"

[Shai Berger]

On Saturday 25 June 2016 00:04:30 Tim Graham wrote:
> With the idea of saving characters in the first line, would "Fix #XXX:
> Message" be better than ""Fix #XXX -- Message" also? This saves two
> characters without any loss of readability as far as I see.
>

Is there a real reason for caring either way? Why don't we accept both?

+1 imperative mood.

[Tim Graham]

Reinout, I agree that the imperative mood seems awkward, especially when reading history, but of course I'm influenced by my experience with Django's history. No doubt others find it more natural. I guess if I had my way, we would keep using past tense, although I will say that it gets a bit tiresome correcting the messages of contributors who don't read our contributing guidelines.

Shai, about "Why don't we accept both?" -- I think it's nice to have a standard format so we don't have to parse visual differences when browsing git log.

[Kevin Christopher Henry]

If anyone's put off by the hectoring tone of the imperative mood, it might be better to think of it as the indicative mood. That is:

(This will) "add password validation to prevent the usage of...".

rather than

(You must) "add password validation to prevent the usage of..."!

In English they're usually expressed the same way, but not so in other languages. Anecdotally, I saw someone comment that in Portuguese the two are different and that the indicative, but not the imperative, would make sense for a commit message. Reinout, I'm curious if that distinction would make a difference in your native language?

For what it's worth, I'm in favor of both proposed changes.

Cheers,
Kevin

[Reinout van Rees]

Op 26-06-16 om 05:31 schreef Kevin Christopher Henry:

> If anyone's put off by the hectoring tone of the imperative mood, it
> might be better to think of it as the indicative mood. That is:
>
> (This will) "add password validation to prevent the usage of...".
>
> rather than
>
> (You must) "add password validation to prevent the usage of..."!

"It might be better to think of it as...": it is exactly this extra
thinkwork that everyone reading the messages has to do. We write it once
and read it many times: what should we optimize for?
In our source code, the answer is clearly that you should optimize for
readability.
Why is it suddenly different for commit messages?

Git will probably be replaced by an even better tool in 5 years' time
(just like svn before that and cvs before): will we go back to the
original proper English then?

> In English they're usually expressed the same way, but not so in other
> languages. Anecdotally, I saw someone comment that in Portuguese the two
> are different and that the indicative, but not the imperative, would
> make sense for a commit message. Reinout, I'm curious if that
> distinction would make a difference in your native language?

In Dutch, the imperative and indicative are different.
But that would be better solved by using the indicative also in English,
right?

- "Adds password validation to prevent..."

The changelog will now look just like installation instructions:

- Install django using `pip install django`.

- Add a database.

- Run `python manage.py ....`

[Riccardo Magliocchetti]

Il 27/06/2016 11:49, Reinout van Rees ha scritto:
> Op 26-06-16 om 05:31 schreef Kevin Christopher Henry:
>> If anyone's put off by the hectoring tone of the imperative mood, it
>> might be better to think of it as the indicative mood. That is:
>>
>> (This will) "add password validation to prevent the usage of...".
>>
>> rather than
>>
>> (You must) "add password validation to prevent the usage of..."!
>
> "It might be better to think of it as...": it is exactly this extra thinkwork
> that everyone reading the messages has to do. We write it once and read it many
> times: what should we optimize for?
> In our source code, the answer is clearly that you should optimize for readability.
> Why is it suddenly different for commit messages?

I think you are overthinking here :) just look at django commit history vs the
git or the linux one. Which commit message would you like to when chasing a bug?

They have a far better culture at that to what in my experience have found in
the python ecosystem. So let's just copy that :)

--
Riccardo Magliocchetti
@rmistaken

[Raphael Hertzog]

Hi,

Le lundi 27 juin 2016, Reinout van Rees a écrit :
> > (You must) "add password validation to prevent the usage of..."!
>
> "It might be better to think of it as...": it is exactly this extra
> thinkwork that everyone reading the messages has to do. We write it once and
> read it many times: what should we optimize for?
> In our source code, the answer is clearly that you should optimize for
> readability.
> Why is it suddenly different for commit messages?

The first persons reading the commit messages are the persons
reviewing the pull requests and for them, it is quite natural to see
the commit message as "(If merged, this will) fix foo".

Even for someone reading the commits after they have been merged,
when they are clearly history, it's not particularly complicated
to read them as "(This commit did) fix foo".

While this looks like some extra thinkwork, I don't think it's
particularly problematic, and it's defininetely not on the scale
of unreadable code. Whatever the tense used, if the commit message
has the required information, the reader will figure it out.

I have no special preference, but this thread pointed me towards some
widely agreed convention and I'm thankful for that since I tend to always
hesitate when writing a commit message. Now I will stick to the git
convention.

Cheers,
--
Raphaël Hertzog ◈ Writer/Consultant ◈ Debian Developer

Discover the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/

[Daniele Procida]

On Mon, Jun 27, 2016, Reinout van Rees <rei...@vanrees.org> wrote:

>Op 26-06-16 om 05:31 schreef Kevin Christopher Henry:
>> If anyone's put off by the hectoring tone of the imperative mood, it
>> might be better to think of it as the indicative mood. That is:
>>
>> (This will) "add password validation to prevent the usage of...".
>>
>> rather than
>>
>> (You must) "add password validation to prevent the usage of..."!
>
>"It might be better to think of it as...": it is exactly this extra
>thinkwork that everyone reading the messages has to do. We write it once
>and read it many times: what should we optimize for?
>In our source code, the answer is clearly that you should optimize for
>readability.
>Why is it suddenly different for commit messages?

I'm inclined to agree with Reinout that a descriptive message makes more sense and is easier to understand than one written in the form of an instruction.

Why would a log record be written as an imperative?

"Updated gnools" tells you what has happened (and even "Updates gnools" is a label saying what the thing it's attached to will do).

"Update gnools" would make sense as the label for an interface button, but not really as a record in a log.

Apart from consistency with Git's own messages, I don't really see the advantage.

Daniele

[Wim Feijen]

I agree with Reinout and on the use of the present tense, so a commit message would read:

"Adds password validation to prevent the usage of ..."

My mind finds this way easier to understand than: "Add password validation ..."

Wim

[Tim Graham]

As it seems there isn't consensus on this and the current message format works fine as far as I'm concerned, I'm dropping the proposal.

I thought the question "if we adopt some new SCM tool that has a different commit message format, would we adopt that format?" is an interesting one.

[Jozef Knaperek]

I've read all your comments and I understand the "readability matters" arguments, but I think we're looking at it from a wrong angle.

Commit message is not a history record. Commit is a diff, and commit message should be a human version of that diff. Please keep in mind that commits can be (re)played in both direction to do/undo changes. So, it is actually more readable to use the imperative/indicative mood, because you expect it to match the meaning of diff.

GIT is not going anyway, it's here to stay for a long time. But this is not GIT specific that much - diffs are here for many decades. I think the question we should ask is: How Is Django as a software project so much different from the whole world that it cannot follow the standard style of a tool it uses so heavily? Should we not keep the philosophy part for GIT authors, and then, even if we do no agree with it 100%, try to adopt it as much as possible just for the sake of consistency? In the whole thread there were no really strong arguments against this, so I believe the decision should be obvious - just use the standard way.

--
Jozef Knaperek