In what tense should the changelog be written?
When one writes one's "blurb" for the changelog, in what tense should it be? I mostly see entries in present tense: bpo-43660: Fix crash that happens when replacing sys.stderr with a callable that can remove the object while an exception is being printed. Patch by Pablo Galindo. bpo-41561: Add workaround for Ubuntu’s custom OpenSSL security level policy. But occasionally I see entries in past tense: bpo-26053: Fixed bug where the pdb interactive run command echoed the args from the shell command line, even if those have been overridden at the pdb prompt. bpo-40630: Added tracemalloc.reset_peak() to set the peak size of traced memory blocks to the current size, to measure the peak of specific pieces of code. I couldn't find any guidance in the Python Dev Guide after sixty seconds of poking around. Obviously this isn't a big deal. But it might be nice to try and nudge everybody in the same direction. It'd be pleasant if the changelog read in a more unified voice, and using the same tense and sentence structure would help towards that goal. If we arrived at a firm decision, maybe "blurb" et al could add a little text suggesting the proper style. Cheers, //arry/
There’s something in the dev guide, but not about tense. Worth adding. (My pet peeve is not to write “The foo module resets the bar state when spam happens,” because that isn’t clear about whether that’s the before or after behavior.) On Thu, Apr 29, 2021 at 17:37 Ethan Furman <ethan@stoneleaf.us> wrote:
On 4/29/21 7:57 PM, Larry Hastings wrote:
When one writes one's "blurb" for the changelog, in what tense should it be?
Present tense. :)
-- ~Ethan~ _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/AM3TQUXV... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido (mobile)
I'll wait to see if anybody else has contrary opinions, but for now here's a first draft: Your NEWS entry should be written in the present tense, and should start with a verb: * Added foo [...] * Changed bar [...] * Removed bat [...] * Fixed buffalo.spam [...] Function and class names should not be followed by parentheses, unless demonstrating an example call. //arry/ On 4/29/21 9:15 PM, Guido van Rossum wrote:
There’s something in the dev guide, but not about tense. Worth adding. (My pet peeve is not to write “The foo module resets the bar state when spam happens,” because that isn’t clear about whether that’s the before or after behavior.)
On Thu, Apr 29, 2021 at 17:37 Ethan Furman <ethan@stoneleaf.us <mailto:ethan@stoneleaf.us>> wrote:
On 4/29/21 7:57 PM, Larry Hastings wrote:
> When one writes one's "blurb" for the changelog, in what tense should it be?
Present tense. :)
-- ~Ethan~ _______________________________________________ Python-Dev mailing list -- python-dev@python.org <mailto:python-dev@python.org> To unsubscribe send an email to python-dev-leave@python.org <mailto:python-dev-leave@python.org> https://mail.python.org/mailman3/lists/python-dev.python.org/ <https://mail.python.org/mailman3/lists/python-dev.python.org/> Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/AM3TQUXV... <https://mail.python.org/archives/list/python-dev@python.org/message/AM3TQUXVNKGOAEC2GBVNUZAZOCLAD6N3/> Code of Conduct: http://python.org/psf/codeofconduct/ <http://python.org/psf/codeofconduct/>
-- --Guido (mobile)
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/FNV3QHWZ... Code of Conduct: http://python.org/psf/codeofconduct/
D'oh! I have a second draft already. Your NEWS entry should be written in the /present tense,/ and should start with a verb: * Add foo [...] * Change bar [...] * Remove bat [...] * Fix buffalo.spam [...] Function and class names should not be followed by parentheses, unless demonstrating an example call. Slapping my forehead, //arry/ On 4/29/21 9:50 PM, Larry Hastings wrote:
I'll wait to see if anybody else has contrary opinions, but for now here's a first draft:
Your NEWS entry should be written in the present tense, and should start with a verb:
* Added foo [...] * Changed bar [...] * Removed bat [...] * Fixed buffalo.spam [...]
Function and class names should not be followed by parentheses, unless demonstrating an example call.
//arry/
On 4/29/21 9:15 PM, Guido van Rossum wrote:
There’s something in the dev guide, but not about tense. Worth adding. (My pet peeve is not to write “The foo module resets the bar state when spam happens,” because that isn’t clear about whether that’s the before or after behavior.)
On Thu, Apr 29, 2021 at 17:37 Ethan Furman <ethan@stoneleaf.us <mailto:ethan@stoneleaf.us>> wrote:
On 4/29/21 7:57 PM, Larry Hastings wrote:
> When one writes one's "blurb" for the changelog, in what tense should it be?
Present tense. :)
-- ~Ethan~ _______________________________________________ Python-Dev mailing list -- python-dev@python.org <mailto:python-dev@python.org> To unsubscribe send an email to python-dev-leave@python.org <mailto:python-dev-leave@python.org> https://mail.python.org/mailman3/lists/python-dev.python.org/ <https://mail.python.org/mailman3/lists/python-dev.python.org/> Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/AM3TQUXV... <https://mail.python.org/archives/list/python-dev@python.org/message/AM3TQUXVNKGOAEC2GBVNUZAZOCLAD6N3/> Code of Conduct: http://python.org/psf/codeofconduct/ <http://python.org/psf/codeofconduct/>
-- --Guido (mobile)
_______________________________________________ Python-Dev mailing list --python-dev@python.org To unsubscribe send an email topython-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived athttps://mail.python.org/archives/list/python-dev@python.org/message/FNV3QHWZ... Code of Conduct:http://python.org/psf/codeofconduct/
On Thu, 29 Apr 2021 21:52:14 -0700 Larry Hastings <larry@hastings.org> wrote:
D'oh! I have a second draft already.
Your NEWS entry should be written in the /present tense,/ and should start with a verb:
* Add foo [...] * Change bar [...] * Remove bat [...] * Fix buffalo.spam [...]
Function and class names should not be followed by parentheses, unless demonstrating an example call.
Slapping my forehead,
You probably mean "Slap my forehead". Regards Antoine.
On Apr 30, 2021, at 04:11, Antoine Pitrou <antoine@python.org> wrote:
On Thu, 29 Apr 2021 21:52:14 -0700 Larry Hastings <larry@hastings.org> wrote:
D'oh! I have a second draft already.
Your NEWS entry should be written in the /present tense,/ and should start with a verb:
* Add foo [...] * Change bar [...] * Remove bat [...] * Fix buffalo.spam [...]
Function and class names should not be followed by parentheses, unless demonstrating an example call.
Slapping my forehead,
You probably mean "Slap my forehead”.
Actually, he probably meant “Slappa da bayss”. -Barry P.S. I was going to say that I prefer past tense when writing news items, but then I looked at the change log files for some of my personal projects and I came to the shocking realization that I actually don’t! Looks like the FLUFL prefers present tense. I do however like to use parentheses for functions and methods. -Barry
On Fri, Apr 30, 2021 at 6:57 AM Larry Hastings <larry@hastings.org> wrote:
Your NEWS entry should be written in the present tense, and should start with a verb:
Add foo [...] Change bar [...] Remove bat [...] Fix buffalo.spam [...]
You might suggest using "now" when describing a behavior change: "foo now does this new thing [...]"
Function and class names should not be followed by parentheses, unless demonstrating an example call.
Oh, I love putting parentheses when mentionning a function: "foo() now does thigs new thing". Also, I like to use :func:`foo` Sphinx markup to add a link in the changelog, and Sphinx adds parentheses for me *but* I don't add parentheses :-) By the way, I recently discovered that :data:, :func:, :option:, etc. accept references written as <ref>. Examples: * :option:`-X utf8 <-X>` * :data:`sys.flags.dev_mode <sys.flags>` * :c:func:`Py_TYPE(self) <Py_TYPE>` * :func:`map(f, iterA, iterB, ...) <map>` I like it! It's convenient to document a function call with arguements, so the arguments can be named in the sentence (like "self" in "Py_TYPE(self)"). Victor -- Night gathers, and now my watch begins. It shall not end until my death.
On 4/30/21 4:51 AM, Victor Stinner wrote:
On Fri, Apr 30, 2021 at 6:57 AM Larry Hastings <larry@hastings.org> wrote:
Function and class names should not be followed by parentheses, unless demonstrating an example call. Oh, I love putting parentheses when mentionning a function: "foo() now does thigs new thing". Also, I like to use :func:`foo` Sphinx markup to add a link in the changelog, and Sphinx adds parentheses for me *but* I don't add parentheses :-)
I do too, and I definitely do that when I write emails, .txt files, and so on. But--as you point out--Sphinx adds them for you. NEWS blurbs should be written in CPython-docs-compatible ReST, and that includes using :func:`foo` to refer to a function called foo. Sphinx will turn this into a hyperlink to the definition of foo in the docs if it knows where it is; :func:`inspect.signature` and :func:`getattr` both work great. I'm still not sure what markup (if any) to use for Git checkins. On Github I know to use Markdown, and they provide a Markdown edit box. But should I use Markdown when I use "git commit" at the command-line? And why am I bringing this up now? Surely this will only serve to fragment the conversation and confuse the larger issue. Cheers, //arry/
On Thu, Apr 29, 2021 at 09:52:14PM -0700, Larry Hastings wrote:
D'oh! I have a second draft already.
Your NEWS entry should be written in the /present tense,/ and should start with a verb:
Without a subject of the sentence, that's not present tense, it is the imperative mood. "Fix buffalo.spam ..." is a command or suggestion. The imperative is suitable for a list of things which should be done, a TODO list, not a list of things which have already been done. https://grammar.collinsdictionary.com/easy-learning/the-imperative When it comes to "the" present tense, there are (at least?) four, and one looks superficially like the imperative, but they need a subject: # present simple tense "Larry fixes buffalo.spam ..." # present continuous tense "Larry is fixing buffalo.spam ..." # present perfect tense "Larry has fixed buffalo.spam ..." # present perfect continuous tense "Larry has been fixing buffalo.spam ..." https://grammar.collinsdictionary.com/easy-learning/the-present-simple-tense One might get away with an implicit "I" in the present simple tense: [I] fix buffalo.spam ... and readers with a good understanding of English will probably be able to infer the intention (tasks which have already been done, not tasks still to be done) but those whose English skills are not as good will probably struggle.
Hm, I actually like the imperative. In a commit or news message it feels very natural to me. And in that context there is no confusion about whether we’re commanding anyone (maybe we’re commanding git? :-). But I am the ultimate intuitive writer — I never took a class in English grammar or writing style, I just pattern match based on what I have read elsewhere. I don’t even know the names for the tenses (I only use “imperative” because you did). On Fri, Apr 30, 2021 at 02:22 Steven D'Aprano <steve@pearwood.info> wrote:
On Thu, Apr 29, 2021 at 09:52:14PM -0700, Larry Hastings wrote:
D'oh! I have a second draft already.
Your NEWS entry should be written in the /present tense,/ and should start with a verb:
Without a subject of the sentence, that's not present tense, it is the imperative mood.
"Fix buffalo.spam ..."
is a command or suggestion. The imperative is suitable for a list of things which should be done, a TODO list, not a list of things which have already been done.
https://grammar.collinsdictionary.com/easy-learning/the-imperative
When it comes to "the" present tense, there are (at least?) four, and one looks superficially like the imperative, but they need a subject:
# present simple tense "Larry fixes buffalo.spam ..."
# present continuous tense "Larry is fixing buffalo.spam ..."
# present perfect tense "Larry has fixed buffalo.spam ..."
# present perfect continuous tense "Larry has been fixing buffalo.spam ..."
https://grammar.collinsdictionary.com/easy-learning/the-present-simple-tense
One might get away with an implicit "I" in the present simple tense:
[I] fix buffalo.spam ...
and readers with a good understanding of English will probably be able to infer the intention (tasks which have already been done, not tasks still to be done) but those whose English skills are not as good will probably struggle.
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/BEED5L4Y... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido (mobile)
This was also my understanding. The last time I looked at writing good commit messages (a similar form), the standard was to finish the sentence: "This commit will...", e.g. "This commit will fix buffalo.spam" from "Fix buffalo.spam".
On Fri, Apr 30, 2021, 16:28 <nchristopherfox@gmail.com> wrote:
This was also my understanding. The last time I looked at writing good commit messages (a similar form), the standard was to finish the sentence: "This commit will...", e.g. "This commit will fix buffalo.spam" from "Fix buffalo.spam".
I like this a lot. This commit/PR will _______. Is it the objective or what is actually done? There could be a recommended set of "codelabels" for which there are also gh issue/pr labels. Where in the devguide should this be summarized?
A lot of times the present tense in changelogs and similar is the English "historical present", also called "narrative present." When the verb comes first, it is usually imperative, but these shade with context. E.g. * Give class Froz a .bar() method * Adding metaclass gives class Froz a .bar() method I prefer this feeling of narrative present in commits or "what's new" myself. On Fri, Apr 30, 2021, 4:05 PM Guido van Rossum <guido@python.org> wrote:
Hm, I actually like the imperative. In a commit or news message it feels very natural to me. And in that context there is no confusion about whether we’re commanding anyone (maybe we’re commanding git? :-).
But I am the ultimate intuitive writer — I never took a class in English grammar or writing style, I just pattern match based on what I have read elsewhere. I don’t even know the names for the tenses (I only use “imperative” because you did).
On Fri, Apr 30, 2021 at 02:22 Steven D'Aprano <steve@pearwood.info> wrote:
On Thu, Apr 29, 2021 at 09:52:14PM -0700, Larry Hastings wrote:
D'oh! I have a second draft already.
Your NEWS entry should be written in the /present tense,/ and should start with a verb:
Without a subject of the sentence, that's not present tense, it is the imperative mood.
"Fix buffalo.spam ..."
is a command or suggestion. The imperative is suitable for a list of things which should be done, a TODO list, not a list of things which have already been done.
https://grammar.collinsdictionary.com/easy-learning/the-imperative
When it comes to "the" present tense, there are (at least?) four, and one looks superficially like the imperative, but they need a subject:
# present simple tense "Larry fixes buffalo.spam ..."
# present continuous tense "Larry is fixing buffalo.spam ..."
# present perfect tense "Larry has fixed buffalo.spam ..."
# present perfect continuous tense "Larry has been fixing buffalo.spam ..."
https://grammar.collinsdictionary.com/easy-learning/the-present-simple-tense
One might get away with an implicit "I" in the present simple tense:
[I] fix buffalo.spam ...
and readers with a good understanding of English will probably be able to infer the intention (tasks which have already been done, not tasks still to be done) but those whose English skills are not as good will probably struggle.
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/BEED5L4Y... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido (mobile) _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/K4AKXIOX... Code of Conduct: http://python.org/psf/codeofconduct/
On Fri, Apr 30, 2021 at 02:22 Steven D'Aprano <steve@pearwood.info <mailto:steve@pearwood.info>> wrote:
Without a subject of the sentence, that's not present tense, it is the imperative mood.
"Fix buffalo.spam ..."
is a command or suggestion.
While it could be read that way, I don't think that's the intention. I'm not sure it fits any of the usual grammatical categories. It might be best understood as an abbreviated infinitive, i.e. there's an implied "The purpose of this commit is to..." in front of it. -- Greg
On Thu, Apr 29, 2021 at 09:52:14PM -0700, Larry Hastings wrote:
D'oh! I have a second draft already.
Your NEWS entry should be written in the /present tense,/ and should start with a verb: Without a subject of the sentence, that's not present tense, it is the imperative mood. Tense and mood are different dimensions. This is the present tense, and
On 30/04/2021 13:15, Steven D'Aprano wrote: the imperative mood:
"Fix buffalo.spam ..."
is a command or suggestion. The imperative is suitable for a list of things which should be done, a TODO list, not a list of things which have already been done.
https://grammar.collinsdictionary.com/easy-learning/the-imperative
The reference is not very good at explaining this, perhaps because the mood in English is not obvious. (Sometimes you have to be French.) The instruction "in the present tense, and should start with a verb" doesn't pin it down, at least if you consider context and are liberal about punctuation: # present tense, indicative mood "bpo-41056: Fixes a reference to deallocated stack ..." -> "bpo-41056 fixes ... # present tense, imperative mood "bpo-41094: Fix decoding errors with audit ... " The preference for the imperative mood probably begins with the title of a change *request*, where the imperative is the one obvious choice, don't you think? I think I prefer it, but if blurb does not mine the commit/PR for text, it's not a constraint. If the trail starts with a bug report ("buffalo.spam borks the weeble when x is negative" (present indicative)) then that makes a confusing commit or news message as Guido points out. Jeff
On Fri, Apr 30, 2021 at 6:22 AM Guido van Rossum <guido@python.org> wrote:
There’s something in the dev guide, but not about tense. Worth adding. (My pet peeve is not to write “The foo module resets the bar state when spam happens,” because that isn’t clear about whether that’s the before or after behavior.)
In the past, different people told me that my phrasing was confusing and suggested me to add "now". It kept this habbit: "The foo module *now* resets the bar state when spam happens" Victor
30.04.21 05:57, Larry Hastings пише:
When one writes one's "blurb" for the changelog, in what tense should it be?
See the previous discussion on this topic: https://mail.python.org/archives/list/python-dev@python.org/thread/C342Y73LA... . I always use "fixed", "removed", "added" when describe changes following the rule formulated by Oleg Broytman:
I use past tense to describe what I did on the code, and present simple to describe what the new code does when running.
On Fri, Apr 30, 2021 at 09:43:44AM +0300, Serhiy Storchaka <storchaka@gmail.com> wrote:
30.04.21 05:57, Larry Hastings пише:
When one writes one's "blurb" for the changelog, in what tense should it be?
See the previous discussion on this topic: https://mail.python.org/archives/list/python-dev@python.org/thread/C342Y73LA... .
I always use "fixed", "removed", "added" when describe changes following the rule formulated by Oleg Broytman:
I use past tense to describe what I did on the code, and present simple to describe what the new code does when running.
Thanks, Serhiy, for reminding! I said this about git commit messages, not NEWS items. And even for commit messages I changed my style to be imperative. The widely known advice about git commit messages is: the subject should be a continuation of "When applied this commit will..." So I now use "Implement a feature", "Fix a bug", "Update docs". Oleg. -- Oleg Broytman https://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN.
By the way, https://docs.python.org/dev/whatsnew/3.10.html#improved-modules is inconsistent: "asyncio: Added missing ..." versus "base64: Add base64.b32hexencode() ..." You can also find such inconsistencies in "versionchanged" markups. Victor On Fri, Apr 30, 2021 at 5:01 AM Larry Hastings <larry@hastings.org> wrote:
When one writes one's "blurb" for the changelog, in what tense should it be? I mostly see entries in present tense:
bpo-43660: Fix crash that happens when replacing sys.stderr with a callable that can remove the object while an exception is being printed. Patch by Pablo Galindo.
bpo-41561: Add workaround for Ubuntu’s custom OpenSSL security level policy.
But occasionally I see entries in past tense:
bpo-26053: Fixed bug where the pdb interactive run command echoed the args from the shell command line, even if those have been overridden at the pdb prompt.
bpo-40630: Added tracemalloc.reset_peak() to set the peak size of traced memory blocks to the current size, to measure the peak of specific pieces of code.
I couldn't find any guidance in the Python Dev Guide after sixty seconds of poking around.
Obviously this isn't a big deal. But it might be nice to try and nudge everybody in the same direction. It'd be pleasant if the changelog read in a more unified voice, and using the same tense and sentence structure would help towards that goal.
If we arrived at a firm decision, maybe "blurb" et al could add a little text suggesting the proper style.
Cheers,
/arry
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/SUEPLPRN... Code of Conduct: http://python.org/psf/codeofconduct/
-- Night gathers, and now my watch begins. It shall not end until my death.
participants (14)
-
Antoine Pitrou
-
Barry Warsaw
-
David Mertz
-
Ethan Furman
-
Greg Ewing
-
Guido van Rossum
-
Jeff Allen
-
Larry Hastings
-
nchristopherfox@gmail.com
-
Oleg Broytman
-
Serhiy Storchaka
-
Steven D'Aprano
-
Victor Stinner
-
Wes Turner