Skip to content

Commit 6869922

Browse files
tomschrtomschr
committed
Configure and add Towncrier files
* Add `changelog.d/.gitignore` to keep this directory * Create `changelog.d/README.rst` with some descriptions * Add `changelog.d/_template.rst` as Towncrier template * Add `[tool.towncrier]` section in pyproject.toml * Add "changelog" target into `tox.ini`. Use it like "tox -e changes -- CMD" whereas CMD is a towncrier command. The default "tox -e changes" calls towncrier to create a draft of the changelog file and output it to stdout. * Update documentation and add include a new section "Changelog" included from `changelog.d/README.rst` * Update changelog.d directory and add new files
1 parent 4f1bd28 commit 6869922

15 files changed

+640
-340
lines changed

‎CHANGELOG.rst‎

Lines changed: 54 additions & 337 deletions
Large diffs are not rendered by default.

‎changelog.d/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
!.gitignore

‎changelog.d/234.deprecation.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
In :file:`setup.py` simplified file and remove
2+
``Tox`` and ``Clean`` classes

‎changelog.d/270.feature.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Configure Towncrier (:pr:`273`:)
2+
3+
* Add :file:`changelog.d/.gitignore` to keep this directory
4+
* Create :file:`changelog.d/README.rst` with some descriptions
5+
* Add :file:`changelog.d/_template.rst` as Towncrier template
6+
* Add ``[tool.towncrier]`` section in :file:`pyproject.toml`
7+
* Add "changelog" target into :file:`tox.ini`. Use it like
8+
:command:`tox -e changelog -- CMD` whereas ``CMD`` is a
9+
Towncrier command. The default :command:`tox -e changelog`
10+
calls Towncrier to create a draft of the changelog file
11+
and output it to stdout.
12+
* Update documentation and add include a new section
13+
"Changelog" included from :file:`changelog.d/README.rst`.

‎changelog.d/276.feature.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Document how to create a sublass from :class:`VersionInfo` class

‎changelog.d/290.deprecation.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
For semver 3.0.0-alpha0:
2+
3+
* Remove anything related to Python2
4+
* In :file:`tox.ini` and :file:`.travis.yml`
5+
Remove targets py27, py34, py35, and pypy.
6+
Add py38, py39, and nightly (allow to fail)
7+
* In :file:`setup.py` simplified file and remove
8+
``Tox`` and ``Clean`` classes

‎changelog.d/290.feature.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Prepare semver 3.0.0-alpha0
2+
3+
* Update :file:`README.rst`, mention maintenance
4+
branch ``maint/v2``.

‎changelog.d/291.bugfix.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Disallow negative numbers in VersionInfo arguments
2+
for ``major``, ``minor``, and ``patch``.

‎changelog.d/README.rst‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
The ``changelog.d`` Directory
2+
=============================
3+
4+
.. -text-begin-
5+
6+
A "Changelog" is a record of all notable changes made to a project. Such
7+
a changelog, in our case the :file:`CHANGELOG.rst`, is read by our *users*.
8+
Therefor, any description should be aimed to users instead of describing
9+
internal changes which are only relevant to developers.
10+
11+
To avoid merge conflicts, we use the towncrier_ package to manage our changelog.
12+
13+
The directory :file:`changelog.d` contains "newsfragments" which are short
14+
ReST-formatted files.
15+
On release, those news fragments are compiled into our :file:`CHANGELOG.rst`.
16+
17+
You don't need to install ``towncrier`` yourself, use the :command:`tox` command
18+
to call the tool.
19+
20+
We recommend to follow the steps to make a smooth integration of your changes:
21+
22+
#. After you have created a new pull request (PR), add a new file into the
23+
directory :file:`changelog.d`. Each filename follows the syntax::
24+
25+
<ISSUE>.<TYPE>.rst
26+
27+
where ``<ISSUE>`` is the pull request number, and ``<TYPE>`` is one of:
28+
29+
* ``bugfix``: fixes a reported bug.
30+
* ``deprecation``: informs about deprecation warnings
31+
* ``doc``: improves documentation.
32+
* ``feature``: adds new user facing features.
33+
* ``removal``: removes obsolete or deprecated features.
34+
* ``trivial``: fixes a small typo or internal change that might be noteworthy.
35+
36+
For example: ``123.feature.rst``, ``456.bugfix.rst`` etc.
37+
38+
#. Create the new file with the command::
39+
40+
tox -e changelog -- create 123.feature.rst
41+
42+
The file is created int the :file:`changelog.d` directory.
43+
44+
#. Open the file and add describe your changes.
45+
46+
* Wrap symbols like modules, functions, or classes into double backticks
47+
so they are rendered in a ``monospace font``.
48+
* Prefer simple past tense or constructions with "now".
49+
50+
#. Check your changes with::
51+
52+
tox -e changelog -- check
53+
54+
#. Optionally, build a draft version of the changelog file with the command::
55+
56+
tox -e changelog
57+
58+
#. Commit all your changes and push it.
59+
60+
61+
This finishes your steps.
62+
63+
On release, the maintainer compiles a new :file:`CHANGELOG.rst` file by running::
64+
65+
tox -e changelog -- build
66+
67+
This will remove all newsfragments inside the :file:`changelog.d` directory,
68+
making it ready for the next release.
69+
70+
71+
72+
.. _towncrier: https://pypi.org/project/towncrier

‎changelog.d/_template.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
{% for section, _ in sections.items() %}
2+
{% set underline = underlines[0] %}{% if section %}{{section}}
3+
{{ underline * section|length }}{% set underline = underlines[1] %}
4+
5+
{% endif %}
6+
7+
:Released: {{ versiondata.date }}
8+
:Maintainer:
9+
10+
11+
{% if sections[section] %}
12+
{% for category, val in definitions.items() if category in sections[section] %}
13+
{{ definitions[category]['name'] }}
14+
{{ underline * definitions[category]['name']|length }}
15+
16+
{% if definitions[category]['showcontent'] %}
17+
{% for text, values in sections[section][category].items() %}
18+
{%- for value in values %}
19+
{% if value.startswith("pr") %}
20+
* :pr:`{{ value[2:] }}`{% else %}
21+
* :gh:`{{ value[1:] }}`{% endif %}{%- endfor -%}: {{ text }}
22+
23+
{% endfor %}
24+
25+
{% else %}
26+
- {{ sections[section][category]['']|join(', ') }}
27+
28+
{% endif %}
29+
{% if sections[section][category]|length == 0 %}
30+
No significant changes.
31+
32+
{% else %}
33+
{% endif %}
34+
35+
{% endfor %}
36+
{% else %}
37+
No significant changes.
38+
39+
40+
{% endif %}
41+
{% endfor %}
42+
----

0 commit comments

Comments
 (0)