On Fri, Apr 30, 2021 at 6:57 AM Larry Hastings <la...@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. _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@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/QO6IDVU2ZHPHSPJA7GLIFNEKDTGDPWMQ/ Code of Conduct: http://python.org/psf/codeofconduct/
