Re: change commit message format to present tense?
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 On Saturday, June 25, 2016 at 9:29:15 PM UTC-4, Tim Graham wrote: > > 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. > > On Saturday, June 25, 2016 at 10:23:59 AM UTC-4, Reinout van Rees wrote: >> >> 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" >> >> -- 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-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@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/24da9fcf-7a9e-4cde-8af6-8673fdcaebaa%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: change commit message format to present tense?
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. On Saturday, June 25, 2016 at 10:23:59 AM UTC-4, Reinout van Rees wrote: > > 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" > > -- 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-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@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/16e71c88-bdaa-4aed-91fe-4e561c5cc21b%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: change commit message format to present tense?
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.
Re: Adding a database-agnostic JSONField into Django
On Friday 24 June 2016 14:49:54 Raphael Hertzog wrote: > > Did my answer clear your doubts? > It moves my opinion of the feature from -0.5 "are we sure we need this" to -0 "I won't stand in your way". Shai.
Re: change commit message format to present tense?
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/ rein...@vanrees.org http://www.nelen-schuurmans.nl/ "Learning history by destroying artifacts is a time-honored atrocity" -- 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-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@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/nkm456%24qhb%241%40ger.gmane.org. For more options, visit https://groups.google.com/d/optout.
