python-semver · tomschr · Apr 19, 2020
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -6,6 +6,20 @@ Change Log
 All notable changes to this code base will be documented in this file,
 in every released version.
 
+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.
+
+..
+   Do *NOT* add changelog entries here!
+
+   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.
+
+.. towncrier release notes start
+
 
 Version 2.10.2
 ==============
@@ -32,13 +46,17 @@ Additions
 n/a
 
 Deprecations
---------
+------------
 
 * :gh:`160` (:pr:`264`):
     * :func:`semver.max_ver`
     * :func:`semver.min_ver`
 
 
+----
+
+
+
 Version 2.10.1
 ==============
 
@@ -62,6 +80,9 @@ Bug Fixes
   to always return a ``VersionInfo`` instance.
 
 
+----
+
+
 Version 2.10.0
 ==============
 
@@ -92,7 +113,7 @@ Additions
 
 
 Deprecations
---------
+------------
 * :gh:`225` (:pr:`229`): Output a DeprecationWarning for the following functions:
 
   - ``semver.parse``
@@ -109,6 +130,8 @@ Deprecations
   These deprecated functions will be removed in semver 3.
 
 
+----
+
 
 Version 2.9.1
 =============
@@ -135,6 +158,8 @@ Bug Fixes
 * :gh:`192` (:pr:`193`): Fixed "pysemver" and "pysemver bump" when called without arguments
 
 
+----
+
 Version 2.9.0
 =============
 :Released: 2019-10-30
@@ -178,13 +203,16 @@ Removals
 * :gh:`148` (:pr:`149`): Removed and replaced ``python setup.py test``
 
 
+----
+
 Version 2.8.2
 =============
 :Released: 2019-05-19
 :Maintainer: Sébastien Celles <s.celles@gmail.com>
 
 Skipped, not released.
 
+----
 
 Version 2.8.1
 =============
@@ -206,6 +234,8 @@ Bug Fixes
 * :gh:`96` (:pr:`97`): Made VersionInfo immutable
 
 
+----
+
 Version 2.8.0
 =============
 :Released: 2018-05-16
@@ -230,6 +260,9 @@ Removals
 * :gh:`76` (:pr:`80`): Removed Python 2.6 compatibility
 
 
+----
+
+
 Version 2.7.9
 =============
 
@@ -243,6 +276,8 @@ Additions
 * :gh:`65` (:pr:`66`): Added :func:`semver.finalize_version` function.
 
 
+----
+
 Version 2.7.8
 =============
 
@@ -252,6 +287,8 @@ Version 2.7.8
 * :gh:`62`: Support custom default names for pre and build
 
 
+----
+
 Version 2.7.7
 =============
 
@@ -262,6 +299,8 @@ Version 2.7.7
 * :pr:`56`: Added support for Python 3.6
 
 
+----
+
 Version 2.7.2
 =============
 
@@ -286,6 +325,8 @@ Bug Fixes
   the prerelease version.
 
 
+----
+
 Version 2.6.0
 =============
 
@@ -301,6 +342,8 @@ Removals
   ignored in comparisons.
 
 
+----
+
 Version 2.5.0
 =============
 
@@ -318,6 +361,8 @@ Changes
 * Made separate builds for tests on Travis CI.
 
 
+----
+
 Version 2.4.2
 =============
 
@@ -336,6 +381,8 @@ Changes
 * Added configuration for Tox test runner.
 
 
+----
+
 Version 2.4.1
 =============
 
@@ -348,6 +395,8 @@ Additions
 * :gh:`23`: Compared build component of a version.
 
 
+----
+
 Version 2.4.0
 =============
 
@@ -360,6 +409,8 @@ Bug Fixes
 * :gh:`21`: Compared alphanumeric components correctly.
 
 
+----
+
 Version 2.3.1
 =============
 
@@ -372,6 +423,8 @@ Additions
 * Declared granted license name in distribution metadata.
 
 
+----
+
 Version 2.3.0
 =============
 
@@ -385,6 +438,8 @@ Additions
   version.
 
 
+----
+
 Version 2.2.1
 =============
 
@@ -397,6 +452,8 @@ Bug Fixes
 * Corrected comparison when any component includes zero.
 
 
+----
+
 Version 2.2.0
 =============
 
@@ -411,6 +468,8 @@ Additions
 * Add code examples for recently-added functions.
 
 
+----
+
 Version 2.1.2
 =============
 
@@ -423,6 +482,8 @@ Bug Fixes
 * Restored current README document to distribution manifest.
 
 
+----
+
 Version 2.1.1
 =============
 
@@ -435,6 +496,8 @@ Bug Fixes
 * Removed absent document from distribution manifest.
 
 
+----
+
 Version 2.1.0
 =============
 
@@ -463,6 +526,8 @@ Bug Fixes
 * Corrected code examples in README document.
 
 
+----
+
 Version 2.0.2
 =============
 
@@ -477,6 +542,8 @@ Additions
 * Explicitly declared supported Python versions.
 
 
+----
+
 Version 2.0.1
 =============
 
@@ -489,6 +556,8 @@ Bug Fixes
 * :gh:`9`: Fixed comparison of equal version strings.
 
 
+----
+
 Version 2.0.0
 =============
 
@@ -508,6 +577,8 @@ Changes
 * Ignore build component for comparison.
 
 
+----
+
 Version 0.0.2
 =============
 
@@ -520,6 +591,8 @@ Changes
 * Use standard library Distutils for distribution management.
 
 
+----
+
 Version 0.0.1
 =============
 

diff --git a/changelog.d/.gitignore b/changelog.d/.gitignore
@@ -0,0 +1 @@
+!.gitignore
diff --git a/changelog.d/236.deprecation.rst b/changelog.d/236.deprecation.rst
@@ -0,0 +1,6 @@
+Output a DeprecationWarning for the following functions:
+
+* ``semver.compare``
+* ``semver.match``
+* ``semver.max_ver``
+* ``semver.min_ver``
diff --git a/changelog.d/270.feature.rst b/changelog.d/270.feature.rst
@@ -0,0 +1,2 @@
+:gh:`270`: Use towncrier to build ``CHANGELOG.rst`` file
+See ``changelog.d/README.rst`` for details.
diff --git a/changelog.d/README.rst b/changelog.d/README.rst
@@ -0,0 +1,72 @@
+The ``changelog.d`` Directory
+=============================
+
+.. -text-begin-
+
+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::
+
+    <ISSUE>.<TYPE>.rst
+
+   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::
+
+     tox -e changelog -- create 123.feature.rst
+
+   The file is created int the :file:`changelog.d` directory.
+
+#. 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::
+
+     tox -e changelog -- check
+
+#. Optionally, build a draft version of the changelog file with the command::
+
+    tox -e changelog
+
+#. Commit all your changes and push it.
+
+
+This finishes your steps.
+
+On release, the maintainer compiles a new :file:`CHANGELOG.rst` file by running::
+
+   tox -e changelog -- build
+
+This will remove all newsfragments inside the :file:`changelog.d` directory,
+making it ready for the next release.
+
+
+
+.. _towncrier: https://pypi.org/project/towncrier
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		:gh:`270`: Use towncrier to build ``CHANGELOG.rst`` file
		See ``changelog.d/README.rst`` for details.