Changes for the upcoming release can be found in

the `"changelog.d" directory <https://github.com/python-semver/python-semver/tree/master/changelog.d>`_

in our repository.

This changelog is managed by towncrier and is compiled at release time.

See https://python-semver.rtd.io/en/latest/development.html#changelog

for details.

Output a DeprecationWarning for the following functions:

* ``semver.compare``

* ``semver.match``

* ``semver.max_ver``

* ``semver.min_ver``

:gh:`270`: Use towncrier to build ``CHANGELOG.rst`` file

See ``changelog.d/README.rst`` for details.

The ``changelog.d`` Directory

A "Changelog" is a record of all notable changes made to a project. Such

a changelog, in our case the :file:`CHANGELOG.rst`, is read by our *users*.

Therefor, any description should be aimed to users instead of describing

internal changes which are only relevant to developers.

To avoid merge conflicts, we use the towncrier_ package to manage our changelog.

The directory :file:`changelog.d` contains "newsfragments" which are short

ReST-formatted files.

On release, those news fragments are compiled into our :file:`CHANGELOG.rst`.

You don't need to install ``towncrier`` yourself, use the :command:`tox` command

to call the tool.

We recommend to follow the steps to make a smooth integration of your changes:

#. After you have created a new pull request (PR), add a new file into the

directory :file:`changelog.d`. Each filename follows the syntax::

where ``<ISSUE>`` is the pull request number, and ``<TYPE>`` is one of:

* ``bugfix``: fixes a reported bug.

* ``deprecation``: informs about deprecation warnings

* ``doc``: improves documentation.

* ``feature``: adds new user facing features.

* ``removal``: removes obsolete or deprecated features.

* ``trivial``: fixes a small typo or internal change that might be noteworthy.

For example: ``123.feature.rst``, ``456.bugfix.rst`` etc.

#. Create the new file with the command::

#. Open the file and add describe your changes.

* Wrap symbols like modules, functions, or classes into double backticks

so they are rendered in a ``monospace font``.

* Prefer simple past tense or constructions with "now".

#. Check your changes with::

#. Optionally, build a draft version of the changelog file with the command::

#. Commit all your changes and push it.

This finishes your steps.

On release, the maintainer compiles a new :file:`CHANGELOG.rst` file by running::

This will remove all newsfragments inside the :file:`changelog.d` directory,

making it ready for the next release.

.. _towncrier: https://pypi.org/project/towncrier