Skip to content

Commit cbd4335

Browse files
tomschrtlaferriere
tomschr
and
tlaferriere
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 * Add news file in changelog.d Co-authored-by: Thomas Laferriere <t.laferriere@hotmail.ca>
1 parent 24bcdfd commit cbd4335

17 files changed

+682
-356
lines changed

‎CHANGELOG.rst

Lines changed: 56 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/213.improvement.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Add typing information

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

‎changelog.d/pr290.deprecation.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
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
9+
* Remove old Python versions (2.7, 3.4, 3.5, and pypy)
10+
from Travis

0 commit comments

Comments
 (0)