Move changelog to towncrier (#236)

.travis.yml

@@ -31,6 +31,8 @@ matrix:
       env: TOXENV=docs
     - python: "3.6"
       env: TOXENV=readme
+    - python: "3.6"
+      env: TOXENV=changelog
 
 
 install:

CHANGELOG.rst

@@ -4,33 +4,7 @@ Changelog
 Versions follow `CalVer <http://calver.org>`_ with a strict backwards compatibility policy.
 The third digit is only for regressions.
 
-
-17.3.0 (UNRELEASED)
--------------------
-
-
-Backward-incompatible changes:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*none*
-
-
-Deprecations:
-^^^^^^^^^^^^^
-
-*none*
-
-
-Changes:
-^^^^^^^^
-
-- ``super()`` and ``__class__`` now work on Python 3 when ``slots=True``.
-  `#102 <https://github.com/python-attrs/attrs/issues/102>`_
-  `#226 <https://github.com/python-attrs/attrs/issues/226>`_
-- The combination of ``str=True`` and ``slots=True`` now works on Python 2.
-  `#198 <https://github.com/python-attrs/attrs/issues/198>`_
-- ``attr.Factory`` is hashable again.
-  `#204 <https://github.com/python-attrs/attrs/issues/204>`_
+.. towncrier release notes start
 
 
 ----
@@ -40,7 +14,7 @@ Changes:
 -------------------
 
 
-Backward-incompatible changes:
+Backward-incompatible Changes:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 *none*
@@ -74,7 +48,7 @@ To encourage more participation, the project has also been moved into a `dedicat
    :alt: attrs logo
 
 
-Backward-incompatible changes:
+Backward-incompatible Changes:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - ``attrs`` will set the ``__hash__()`` method to ``None`` by default now.
@@ -200,7 +174,7 @@ Changes:
 16.1.0 (2016-08-30)
 -------------------
 
-Backward-incompatible changes:
+Backward-incompatible Changes:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - All instances where function arguments were called ``cl`` have been changed to the more Pythonic ``cls``.
@@ -244,7 +218,7 @@ Changes:
 16.0.0 (2016-05-23)
 -------------------
 
-Backward-incompatible changes:
+Backward-incompatible Changes:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - Python 3.3 and 2.6 aren't supported anymore.

CONTRIBUTING.rst

@@ -86,17 +86,50 @@ Documentation
 
      First line of new section.
 - If you add a new feature, demonstrate its awesomeness in the `examples page`_!
-- If your change is noteworthy, add an entry to the changelog_.
-  Use `semantic newlines`_, and add a link to your pull request:
+
+
+Changelog
+^^^^^^^^^
+
+If your change is noteworthy, there needs to be a changelog entry, so our users can learn about it!
+
+To avoid merge conflicts, we use the towncrier_ package to manage our changelog.
+``towncrier`` uses independent files for each pull request -- so called *news fragments* -- instead of one monolithic changelog file.
+On release those news fragments are compiled into our ``CHANGELOG.rst``.
+
+You don't need to install ``towncrier`` yourself, you just have to abide to a few simple rules:
+
+- For each pull request, add a new file into ``changelog.d`` with a filename adhering to the ``pr#.(change|deprecation|breaking).rst`` schema:
+  For example ``changelog.d/42.change.rst`` for a non-breaking change, that is proposed in pull request number 42.
+- As with other docs, please use `semantic newlines`_ within news fragments.
+- Wrap symbols like modules, functions, or classes into double backticks so they are rendered in a monospaced font.
+- If you mention functions or other callables, add parantheses at the end of their names: ``attr.func()`` or ``attr.Class.method()``.
+  This makes the changelog a lot more readable.
+- Prefer simple past or constructions with "now".
+  For example:
+
+  + Added ``attr.validators.func()``.
+  + ``attr.func()`` now doesn't crash the Large Hadron Collider anymore.
+- If you want to reference multiple issues, copy the news fragment to another filename.
+  ``towncrier`` will merge all news fragments with identical contents into one entry with multiple links to the respective pull requests.
+
+Example entries:
 
   .. code-block:: rst
 
-     - Added ``attr.validators.func()``.
-       The feature really *is* awesome.
-       `#1 <https://github.com/python-attrs/attrs/pull/1>`_
-     - ``attr.func()`` now doesn't crash the Large Hadron Collider anymore.
-       The bug really *was* nasty.
-       `#2 <https://github.com/python-attrs/attrs/pull/2>`_
+     Added ``attr.validators.func()``.
+     The feature really *is* awesome.
+
+or:
+
+  .. code-block:: rst
+
+     ``attr.func()`` now doesn't crash the Large Hadron Collider anymore.
+     The bug really *was* nasty.
+
+----
+
+``tox -e changelog`` will render the current changelog to the terminal if you have any doubts.
 
 
 Local Development Environment
@@ -174,3 +207,4 @@ Thank you for considering contributing to ``attrs``!
 .. _CI: https://travis-ci.org/python-attrs/attrs/
 .. _`team of volunteers`: https://github.com/python-attrs
 .. _BDFL: https://en.wikipedia.org/wiki/Benevolent_dictator_for_life
+.. _towncrier: https://pypi.org/project/towncrier

MANIFEST.in

@@ -1,4 +1,4 @@
-include LICENSE *.rst
+include LICENSE *.rst *.toml
 
 # Don't package GitHub-specific files.
 exclude *.md .travis.yml
@@ -13,3 +13,6 @@ recursive-include docs *.png
 recursive-include docs *.py
 recursive-include docs *.rst
 prune docs/_build
+
+# Changelog news fragments -- is empty on releases.
+prune changelog.d

PULL_REQUEST_TEMPLATE.md

@@ -7,6 +7,6 @@ This is just a reminder about the most common mistakes.  Please make sure that y
 - [ ] Updated **documentation** for changed code.
 - [ ] Documentation in `.rst` files is written using [semantic newlines](http://rhodesmill.org/brandon/2012/one-sentence-per-line/).
 - [ ] Changed/added classes/methods/functions have appropriate `versionadded`, `versionchanged`, or `deprecated` [directives](http://www.sphinx-doc.org/en/stable/markup/para.html#directive-versionadded).
-- [ ] Changes (and possible deprecations) are documented in [`CHANGELOG.rst`](https://github.com/python-attrs/attrs/blob/master/CHANGELOG.rst).
+- [ ] Changes (and possible deprecations) have news fragments in [`changelog.d`](https://github.com/python-attrs/attrs/blob/master/changelog.d).
 
 If you have *any* questions to *any* of the points above, just **submit and ask**!  This checklist is here to *help* you, not to deter you from contributing!

changelog.d/102.change

@@ -0,0 +1 @@
+``super()`` and ``__class__`` now work on Python 3 when ``slots=True``.

changelog.d/198.change

@@ -0,0 +1 @@
+The combination of ``str=True`` and ``slots=True`` now works on Python 2.

changelog.d/204.change

@@ -0,0 +1 @@
+``attr.Factory`` is hashable again.

changelog.d/226.change

@@ -0,0 +1 @@
+``super()`` and ``__class__`` now work on Python 3 when ``slots=True``.

pyproject.toml

@@ -0,0 +1,26 @@
+[tool.towncrier]
+    package = "attr"
+    package_dir = "src"
+    filename = "CHANGELOG.rst"
+    issue_format = "`#{issue} <https://github.com/python-attrs/attrs/issues/{issue}>`_"
+    directory = "changelog.d"
+    title_format = "{version} ({project_date})"
+    underlines = ["-", "^"]
+
+    [[tool.towncrier.section]]
+        path = ""
+
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Backward-incompatible Changes"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "change"
+        name = "Changes"
+        showcontent = true

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py27,py34,py35,py36,pypy,pypy3,flake8,manifest,docs,readme,coverage-report
+envlist = py27,py34,py35,py36,pypy,pypy3,flake8,manifest,docs,readme,changelog,coverage-report
 
 
 [testenv]
@@ -51,6 +51,12 @@ deps = readme_renderer
 skip_install = true
 commands = python setup.py check -r -s
 
+[testenv:changelog]
+basepython = python3.6
+deps = towncrier
+skip_install = true
+commands = towncrier --draft
+
 
 # Uses default basepython otherwise reporting doesn't work on Travis where
 # Python 3.6 is only available in 3.6 jobs.