Skip to content

Commit

Permalink
docs/development changelog: Add sample changelog entry; document `:us…
Browse files Browse the repository at this point in the history
…er:`
  • Loading branch information
0cjs committed Jan 24, 2024
1 parent bd85c68 commit 4bcd5e7
Showing 1 changed file with 10 additions and 1 deletion.
11 changes: 10 additions & 1 deletion docs/development.rst
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,8 @@ Contents of a changelog entry

The content of this file is reStructuredText formatted text that will be used as the content of the changelog entry.
You do not need to reference the issue or PR numbers here as towncrier will automatically add a reference to all of the
affected issues when rendering the changelog.
affected issues when rendering the changelog. You may append ``- by :user:USERNAME``, with a GitHub username in
backticks, if you wish.

In order to maintain a consistent style in the ``changelog.rst`` file, it is preferred to keep the entries to the
point, in sentence case, shorter than 120 characters and in an imperative tone -- an entry should complete the sentence
Expand All @@ -220,6 +221,14 @@ by a blank line separating it from a description of the feature/change in one or
characters. Remember that a changelog entry is meant for end users and should only contain details relevant to an end
user.

An example of ``docs/changelog/####.bugfix.rst`` contents is:

.. code-block::
Instead of raising ``UnicodeDecodeError`` when command output includes non-utf-8 bytes, ``tox`` will now use
``surrogateescape`` error handling to convert the unrecognized bytes to escape sequences according to :pep:`383`
- by :user:`masenf`
Becoming a maintainer
~~~~~~~~~~~~~~~~~~~~~
Expand Down

0 comments on commit 4bcd5e7

Please sign in to comment.