From da6179e723043fbc0d0c740538e36191b4170471 Mon Sep 17 00:00:00 2001 From: Thomas Schraitle Date: Sun, 19 Apr 2020 22:36:11 +0200 Subject: [PATCH] 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` --- CHANGELOG.rst | 77 ++++++++++++++++++++++++++++++++- changelog.d/.gitignore | 1 + changelog.d/236.deprecation.rst | 6 +++ changelog.d/270.feature.rst | 2 + changelog.d/README.rst | 72 ++++++++++++++++++++++++++++++ changelog.d/_template.rst | 42 ++++++++++++++++++ changelog.d/pr230.doc.rst | 5 +++ docs/development.rst | 11 +++++ pyproject.toml | 54 +++++++++++++++++++++++ tox.ini | 11 +++++ 10 files changed, 279 insertions(+), 2 deletions(-) create mode 100644 changelog.d/.gitignore create mode 100644 changelog.d/236.deprecation.rst create mode 100644 changelog.d/270.feature.rst create mode 100644 changelog.d/README.rst create mode 100644 changelog.d/_template.rst create mode 100644 changelog.d/pr230.doc.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 25a0d680..0ba8bbeb 100644 --- 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 `_ +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,6 +203,8 @@ Removals * :gh:`148` (:pr:`149`): Removed and replaced ``python setup.py test`` +---- + Version 2.8.2 ============= :Released: 2019-05-19 @@ -185,6 +212,7 @@ Version 2.8.2 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 new file mode 100644 index 00000000..f935021a --- /dev/null +++ b/changelog.d/.gitignore @@ -0,0 +1 @@ +!.gitignore diff --git a/changelog.d/236.deprecation.rst b/changelog.d/236.deprecation.rst new file mode 100644 index 00000000..60e378f8 --- /dev/null +++ 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 new file mode 100644 index 00000000..495a7b7c --- /dev/null +++ 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 new file mode 100644 index 00000000..3ef3c0bc --- /dev/null +++ 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:: + + ..rst + + where ```` is the pull request number, and ```` 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 diff --git a/changelog.d/_template.rst b/changelog.d/_template.rst new file mode 100644 index 00000000..982ad41a --- /dev/null +++ b/changelog.d/_template.rst @@ -0,0 +1,42 @@ +{% for section, _ in sections.items() %} +{% set underline = underlines[0] %}{% if section %}{{section}} +{{ underline * section|length }}{% set underline = underlines[1] %} + +{% endif %} + +:Released: {{ versiondata.date }} +:Maintainer: + + +{% if sections[section] %} +{% for category, val in definitions.items() if category in sections[section] %} +{{ definitions[category]['name'] }} +{{ underline * definitions[category]['name']|length }} + +{% if definitions[category]['showcontent'] %} +{% for text, values in sections[section][category].items() %} +{%- for value in values %} +{% if value.startswith("pr") %} +* :pr:`{{ value[2:] }}`{% else %} +* :gh:`{{ value[1:] }}`{% endif %}{%- endfor -%}: {{ text }} + +{% endfor %} + +{% else %} +- {{ sections[section][category]['']|join(', ') }} + +{% endif %} +{% if sections[section][category]|length == 0 %} +No significant changes. + +{% else %} +{% endif %} + +{% endfor %} +{% else %} +No significant changes. + + +{% endif %} +{% endfor %} +---- diff --git a/changelog.d/pr230.doc.rst b/changelog.d/pr230.doc.rst new file mode 100644 index 00000000..8875ae2c --- /dev/null +++ b/changelog.d/pr230.doc.rst @@ -0,0 +1,5 @@ +Add version information in some functions: + +* Use ``.. versionadded::`` RST directive in docstrings to + make it more visible when something was added +* Minor wording fix in docstrings (versions -> version strings) diff --git a/docs/development.rst b/docs/development.rst index dad14641..ea2298d7 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -1,3 +1,5 @@ +.. _contributing: + Contributing to semver ====================== @@ -185,6 +187,15 @@ documentation includes: edge cases. +.. _changelog: + +Changelog +--------- + +.. include:: ../changelog.d/README.rst + :start-after: -text-begin- + + .. _flake8: https://flake8.readthedocs.io .. _issues: https://github.com/python-semver/python-semver/issues .. _pull request: https://github.com/python-semver/python-semver/pulls diff --git a/pyproject.toml b/pyproject.toml index eca41891..5fb0b30c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,12 @@ +[build-system] +requires = [ + # sync with setup.py until we discard non-pep-517/518 + "setuptools>=40.0", + "setuptools-scm", + "wheel", +] +build-backend = "setuptools.build_meta" + [tool.black] line-length = 88 target-version = ['py37'] @@ -18,3 +27,48 @@ exclude = ''' )/ ) ''' + +[tool.towncrier] +package = "semver" +# package_dir = "src" +filename = "CHANGELOG.rst" +directory = "changelog.d/" +title_format = "Version {version}" +template = "changelog.d/_template.rst" +# issue_format = "`#{issue} `_" +# issue_format = ":gh:`{issue}`" + + [[tool.towncrier.type]] + directory = "breaking" + name = "Breaking Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "deprecation" + name = "Deprecations" + showcontent = true + + [[tool.towncrier.type]] + directory = "feature" + name = "Features" + showcontent = true + + [[tool.towncrier.type]] + directory = "improvement" + name = "Improvements" + showcontent = true + + [[tool.towncrier.type]] + directory = "bugfix" + name = "Bug Fixes" + showcontent = true + + [[tool.towncrier.type]] + directory = "doc" + name = "Improved Documentation" + showcontent = true + + [[tool.towncrier.type]] + directory = "trivial" + name = "Trivial/Internal Changes" + showcontent = true diff --git a/tox.ini b/tox.ini index 833c9655..0b0a82b0 100644 --- a/tox.ini +++ b/tox.ini @@ -44,6 +44,7 @@ commands = {[testenv:flake8]commands} {[testenv:docstrings]commands} + [testenv:docs] description = Build HTML documentation basepython = python3 @@ -51,6 +52,7 @@ deps = -r{toxinidir}/docs/requirements.txt skip_install = true commands = make -C docs html + [testenv:man] description = Build the manpage basepython = python3 @@ -68,3 +70,12 @@ deps = commands = python3 setup.py sdist bdist_wheel --universal twine check dist/* + + +[testenv:changelog] +description = Run towncrier to check, build, or create the CHANGELOG.rst +basepython = python3 +deps = + git+https://github.com/twisted/towncrier.git +commands = + towncrier {posargs:build --draft}