Skip to content

Commit da6179e

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`
1 parent e2532b2 commit da6179e

File tree

10 files changed

+279
-2
lines changed

10 files changed

+279
-2
lines changed

‎CHANGELOG.rst‎

Lines changed: 75 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,20 @@ Change Log
66
All notable changes to this code base will be documented in this file,
77
in every released version.
88

9+
Changes for the upcoming release can be found in
10+
the `"changelog.d" directory <https://github.com/python-semver/python-semver/tree/master/changelog.d>`_
11+
in our repository.
12+
13+
..
14+
Do *NOT* add changelog entries here!
15+
16+
This changelog is managed by towncrier and is compiled at release time.
17+
18+
See https://python-semver.rtd.io/en/latest/development.html#changelog
19+
for details.
20+
21+
.. towncrier release notes start
22+
923
1024
Version 2.10.2
1125
==============
@@ -32,13 +46,17 @@ Additions
3246
n/a
3347

3448
Deprecations
35-
--------
49+
------------
3650

3751
* :gh:`160` (:pr:`264`):
3852
* :func:`semver.max_ver`
3953
* :func:`semver.min_ver`
4054

4155

56+
----
57+
58+
59+
4260
Version 2.10.1
4361
==============
4462

@@ -62,6 +80,9 @@ Bug Fixes
6280
to always return a ``VersionInfo`` instance.
6381

6482

83+
----
84+
85+
6586
Version 2.10.0
6687
==============
6788

@@ -92,7 +113,7 @@ Additions
92113

93114

94115
Deprecations
95-
--------
116+
------------
96117
* :gh:`225` (:pr:`229`): Output a DeprecationWarning for the following functions:
97118

98119
- ``semver.parse``
@@ -109,6 +130,8 @@ Deprecations
109130
These deprecated functions will be removed in semver 3.
110131

111132

133+
----
134+
112135

113136
Version 2.9.1
114137
=============
@@ -135,6 +158,8 @@ Bug Fixes
135158
* :gh:`192` (:pr:`193`): Fixed "pysemver" and "pysemver bump" when called without arguments
136159

137160

161+
----
162+
138163
Version 2.9.0
139164
=============
140165
:Released: 2019-10-30
@@ -178,13 +203,16 @@ Removals
178203
* :gh:`148` (:pr:`149`): Removed and replaced ``python setup.py test``
179204

180205

206+
----
207+
181208
Version 2.8.2
182209
=============
183210
:Released: 2019-05-19
184211
:Maintainer: Sébastien Celles <s.celles@gmail.com>
185212

186213
Skipped, not released.
187214

215+
----
188216

189217
Version 2.8.1
190218
=============
@@ -206,6 +234,8 @@ Bug Fixes
206234
* :gh:`96` (:pr:`97`): Made VersionInfo immutable
207235

208236

237+
----
238+
209239
Version 2.8.0
210240
=============
211241
:Released: 2018-05-16
@@ -230,6 +260,9 @@ Removals
230260
* :gh:`76` (:pr:`80`): Removed Python 2.6 compatibility
231261

232262

263+
----
264+
265+
233266
Version 2.7.9
234267
=============
235268

@@ -243,6 +276,8 @@ Additions
243276
* :gh:`65` (:pr:`66`): Added :func:`semver.finalize_version` function.
244277

245278

279+
----
280+
246281
Version 2.7.8
247282
=============
248283

@@ -252,6 +287,8 @@ Version 2.7.8
252287
* :gh:`62`: Support custom default names for pre and build
253288

254289

290+
----
291+
255292
Version 2.7.7
256293
=============
257294

@@ -262,6 +299,8 @@ Version 2.7.7
262299
* :pr:`56`: Added support for Python 3.6
263300

264301

302+
----
303+
265304
Version 2.7.2
266305
=============
267306

@@ -286,6 +325,8 @@ Bug Fixes
286325
the prerelease version.
287326

288327

328+
----
329+
289330
Version 2.6.0
290331
=============
291332

@@ -301,6 +342,8 @@ Removals
301342
ignored in comparisons.
302343

303344

345+
----
346+
304347
Version 2.5.0
305348
=============
306349

@@ -318,6 +361,8 @@ Changes
318361
* Made separate builds for tests on Travis CI.
319362

320363

364+
----
365+
321366
Version 2.4.2
322367
=============
323368

@@ -336,6 +381,8 @@ Changes
336381
* Added configuration for Tox test runner.
337382

338383

384+
----
385+
339386
Version 2.4.1
340387
=============
341388

@@ -348,6 +395,8 @@ Additions
348395
* :gh:`23`: Compared build component of a version.
349396

350397

398+
----
399+
351400
Version 2.4.0
352401
=============
353402

@@ -360,6 +409,8 @@ Bug Fixes
360409
* :gh:`21`: Compared alphanumeric components correctly.
361410

362411

412+
----
413+
363414
Version 2.3.1
364415
=============
365416

@@ -372,6 +423,8 @@ Additions
372423
* Declared granted license name in distribution metadata.
373424

374425

426+
----
427+
375428
Version 2.3.0
376429
=============
377430

@@ -385,6 +438,8 @@ Additions
385438
version.
386439

387440

441+
----
442+
388443
Version 2.2.1
389444
=============
390445

@@ -397,6 +452,8 @@ Bug Fixes
397452
* Corrected comparison when any component includes zero.
398453

399454

455+
----
456+
400457
Version 2.2.0
401458
=============
402459

@@ -411,6 +468,8 @@ Additions
411468
* Add code examples for recently-added functions.
412469

413470

471+
----
472+
414473
Version 2.1.2
415474
=============
416475

@@ -423,6 +482,8 @@ Bug Fixes
423482
* Restored current README document to distribution manifest.
424483

425484

485+
----
486+
426487
Version 2.1.1
427488
=============
428489

@@ -435,6 +496,8 @@ Bug Fixes
435496
* Removed absent document from distribution manifest.
436497

437498

499+
----
500+
438501
Version 2.1.0
439502
=============
440503

@@ -463,6 +526,8 @@ Bug Fixes
463526
* Corrected code examples in README document.
464527

465528

529+
----
530+
466531
Version 2.0.2
467532
=============
468533

@@ -477,6 +542,8 @@ Additions
477542
* Explicitly declared supported Python versions.
478543

479544

545+
----
546+
480547
Version 2.0.1
481548
=============
482549

@@ -489,6 +556,8 @@ Bug Fixes
489556
* :gh:`9`: Fixed comparison of equal version strings.
490557

491558

559+
----
560+
492561
Version 2.0.0
493562
=============
494563

@@ -508,6 +577,8 @@ Changes
508577
* Ignore build component for comparison.
509578

510579

580+
----
581+
511582
Version 0.0.2
512583
=============
513584

@@ -520,6 +591,8 @@ Changes
520591
* Use standard library Distutils for distribution management.
521592

522593

594+
----
595+
523596
Version 0.0.1
524597
=============
525598

‎changelog.d/.gitignore‎

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

‎changelog.d/236.deprecation.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Output a DeprecationWarning for the following functions:
2+
3+
* ``semver.compare``
4+
* ``semver.match``
5+
* ``semver.max_ver``
6+
* ``semver.min_ver``

‎changelog.d/270.feature.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
:gh:`270`: Use towncrier to build ``CHANGELOG.rst`` file
2+
See ``changelog.d/README.rst`` for details.

‎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

0 commit comments

Comments
 (0)