Switch to towncrier to automatically manage the change log

.github/pull_request_template.md

@@ -10,7 +10,7 @@ Write a description of the fixes or improvements.
 
 ## Checklist
 
-- [ ] I've added a change log entry to `CHANGES.rst`.
+- [ ] I've added a change log entry to `/news`, following the instructions in [Change log entry format](https://icalendar.readthedocs.io/en/latest/contribute/#change-log-entry-format).
 - [ ] I've added or updated tests if applicable.
 - [ ] I've run and ensured all tests pass locally by following [Run tests](https://icalendar.readthedocs.io/en/latest/contribute/development.html#run-tests).
 - [ ] I've added or edited documentation, both as docstrings to be rendered in the API documentation and narrative documentation, as necessary.

.github/workflows/tests.yml

@@ -166,5 +166,5 @@ jobs:
         uses: ncipollo/release-action@v1
         with:
           allowUpdates: true
-          body: "To view the changes, please see the [Changelog](https://icalendar.readthedocs.io/en/latest/changelog.html). This release can be installed from [PyPI](https://pypi.org/project/icalendar/#history)."
+          body: "To view the changes, please see the [Changelog](https://icalendar.readthedocs.io/en/latest/reference/changelog.html). This release can be installed from [PyPI](https://pypi.org/project/icalendar/#history)."
           generateReleaseNotes: false

CHANGES.rst

@@ -4,37 +4,13 @@ Change log
 
 .. py:currentmodule:: icalendar
 
-7.1.1 (unreleased)
-------------------
-
-Minor changes
-~~~~~~~~~~~~~
-
-- Bump PyPy from 3.10 to 3.11 for testing. :pr:`1383`
-- Created an :attr:`~icalendar.prop.dt.period.vPeriod.ical_value` property for the :class:`~icalendar.prop.dt.period.vPeriod` component. :issue:`876`
+.. Do *NOT* add new change log entries to this file.
+   Instead create a file in the news directory.
+   For helpful instructions, see:
+   https://icalendar.readthedocs.io/en/latest/contribute/#change-log-entry-format
 
-Breaking changes
-~~~~~~~~~~~~~~~~
-
-- ...
-
-New features
-~~~~~~~~~~~~
-
-- Created a :meth:`~icalendar.prop.recur.weekday.vWeekday.ical_value` property for the :class:`~icalendar.prop.recur.weekday.vWeekday` component, mirroring the existing pattern on :class:`~icalendar.prop.boolean.vBoolean`. :pr:`1360`
-
-Bug fixes
-~~~~~~~~~
-
-- Strictly validate BINARY property values in
-  :attr:`vBinary.from_ical() <icalendar.prop.binary.vBinary.from_ical>`
-  and reject malformed Base64 input instead of silently accepting invalid
-  characters. :pr:`1349`
-
-Documentation
-~~~~~~~~~~~~~
+.. towncrier release notes start
 
-- Replace the RFC quotations in the docstrings for :attr:`Alarm.REPEAT <icalendar.cal.alarm.Alarm.REPEAT>` and :attr:`Alarm.DURATION <icalendar.cal.alarm.Alarm.DURATION>` with Pythonic descriptions, including parameter notes, conformance references, and worked examples. :issue:`1244`
 
 7.1.0 (2026-04-30)
 ------------------

Makefile

@@ -5,11 +5,13 @@ SHELL           = bash
 # You can set these variables from the command line.
 SPHINXOPTS      ?=
 PAPER           ?=
+VERSION			?=
 
 # Internal variables.
 RUFFPATH        = "$(realpath .venv/bin/ruff)"
-SPHINXBUILD     = "$(realpath .venv/bin/sphinx-build)"
 SPHINXAUTOBUILD = "$(realpath .venv/bin/sphinx-autobuild)"
+SPHINXBUILD     = "$(realpath .venv/bin/sphinx-build)"
+TOWNCRIERPATH   = "$(realpath .venv/bin/towncrier)"
 DOCS_DIR        = ./docs/
 BUILDDIR        = ../_build
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -86,8 +88,8 @@ text: .venv
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-.PHONY: changes
-changes: .venv
+.PHONY: sphinx-changes
+sphinx-changes: .venv
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
@@ -160,3 +162,15 @@ rtd-prepare:  ## Prepare environment on Read the Docs
 rtd-pr-preview: rtd-prepare .venv ## Build pull request preview on Read the Docs
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
 # /deployment
+
+# release
+.PHONY: changes-draft
+changes-draft: dev
+	@test -n "$(VERSION)" || (echo "VERSION is not set. Run 'export VERSION=x.y.z' first." && exit 1)
+	$(TOWNCRIERPATH) build --draft --version ${VERSION} --yes
+
+.PHONY: changes
+changes: dev
+	@test -n "$(VERSION)" || (echo "VERSION is not set. Run 'export VERSION=x.y.z' first." && exit 1)
+	$(TOWNCRIERPATH) build --version ${VERSION} --yes
+# /release

docs/contribute/index.rst

@@ -135,38 +135,84 @@ The maintainers may also take further action, including suspend, ban, or report
 Change log entry format
 ```````````````````````
 
-Add your entry under the appropriate section in :file:`CHANGES.rst`.
+To create a change log entry or news item, create a file in the :file:`news` directory, located in the root of the package.
 
-Minor changes
-    For small improvements, refactoring, and documentation updates.
+The change log entry's format must be ``#.type``, where ``#`` is the referenced GitHub issue or pull request number, ``.`` is the literal extension delimiter, and ``type`` is one of the following strings.
 
-Breaking changes
+``breaking``
     For changes that break the existing API.
 
-New features
+``removal``
+    For removals and deprecations.
+
+``feature``
     For new functionality.
 
-Bug fixes
+``bugfix``
     For bug fixes and error corrections.
 
-Documentation
+``documentation``
     For changes to the documentation, docstrings, spelling dictionary, or any other documentation matter.
 
-Examples:
+``deps``
+    For changes to project dependencies.
+
+``internal``
+    For internal changes, such as issue templates.
+
+``chore``
+    For routine tasks that shouldn't be published, but will satisfy the checker for the presence of a change log entry.
+
+For orphan change log entries—that is, those that don't need to be linked to any issue ID or other identifier—start the file name with ``+``.
+The content will still be included in the change log, at the end of the category corresponding to the file extension.
+
+..  code-block:: text
+
+    +anything.bugfix
+
+.. note::
+
+    icalendar uses `towncrier <https://pypi.org/project/towncrier/>`_ to automatically update the change log from entries stored in the :file:`/news` directory at the root of the project.
+
+
+.. _write-a-good-change-log-entry-label:
+
+Write a good change log entry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+
+    These change log entries become narrative documentation.
+
+The content of this file must include the following.
+
+-   A brief message that summarizes the changes in your contribution.
+-   An attribution to yourself, in the format of ``@github_username``.
+
+You can write a good change log entry with the following guidance.
+
+-   Use a narrative format, in the past tense, proper English spelling and grammar, and inline markup as needed.
+-   Write your change log entry for its appropriate audience.
+
+    -   Most entries should address *users* of the software.
+    -   An entry for a change to a public API should address *developers*.
 
-.. code-block:: rst
+-   If you fix a bug, write what was broken and is now fixed.
+    You should not write *how* you fixed it.
+-   If you add or change a feature or public API, write a summary of previous behavior, what it does now, and how to use it.
+-   Refer to narrative documentation as needed.
 
-    Minor changes:
+The following text is an example of a good change log entry, placed inside :file:`/news/1360.feature`.
 
-    - Fix issue with timezone parsing in special cases. :issue:`1050`
+..  code-block:: rst
 
-For a pull request, use the following syntax.
+    Created a :meth:`~icalendar.prop.recur.weekday.vWeekday.ical_value` property for the :class:`~icalendar.prop.recur.weekday.vWeekday` component, mirroring the existing pattern on :class:`~icalendar.prop.boolean.vBoolean`. @mvanhorn
 
-.. code-block:: rst
+The following would be a poor change log entry.
 
-    New features:
+..  code-block:: rst
 
-    - Added :attr:`~icalendar.cal.calendar.Calendar.categories` property. :pr:`808`
+    Fix #123456 by chaning config of file [did_not_read_this_guide]
 
 
 Set up for development

docs/contribute/maintenance.rst

@@ -122,20 +122,20 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
             # ...
             "show_version_warning_banner": False,
 
-#.  Check that the file :file:`CHANGES.rst` is up to date with the `latest merged pull requests <https://github.com/collective/icalendar/pulls?q=is%3Apr+is%3Amerged>`_, and the version you want to release is correctly named.
-    Change the date of the release, and remove empty sections.
+#.  Update the change log :file:`CHANGES.rst` with the change log entries in :file:`/news` with `towncrier <https://pypi.org/project/towncrier/>`_.
 
-    .. code-block:: diff
+    ..  code-block:: shell
 
-        -7.0.0 (unreleased)
-        +7.0.0 (2026-02-11)
+        make changes
 
 #.  Create a commit on a ``release`` branch to release this version.
 
     .. code-block:: shell
 
         git checkout -b release-$VERSION main
-        git add CHANGES.rst docs/conf.py
+        git checkout -b release-$VERSION main
+        git add CHANGES.rst docs/conf.py news/
+        git commit -m"version $VERSION"
         git commit -m"version $VERSION"
 
 #.  Push the commit and `create a pull request <https://github.com/collective/icalendar/compare?expand=1>`_.
@@ -185,50 +185,6 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
         tests: PyPI is waiting for your review
 
 #.  If the release is approved by a maintainer, it will be pushed to `PyPI`_.
-#.  Copy this to the start of :file:`CHANGES.rst`, and increase the version number.
-
-    .. code-block:: shell
-
-        git checkout main
-        git pull
-
-    .. code-block:: text
-
-       7.0.1 (unreleased)
-       ------------------
-
-       Minor changes
-       ~~~~~~~~~~~~~
-
-       - ...
-
-       Breaking changes
-       ~~~~~~~~~~~~~~~~
-
-       - ...
-
-       New features
-       ~~~~~~~~~~~~
-
-       - ...
-
-       Bug fixes
-       ~~~~~~~~~
-
-       - ...
-
-       Documentation
-       ~~~~~~~~~~~~~
-
-       - ...
-
-#.  Push the changes to :file:`CHANGES.rst` so it is used for future changes.
-
-    .. code-block:: shell
-
-        git add CHANGES.rst
-        git commit -m "Add new CHANGELOG section for future release"
-        git push upstream main # to collective/icalendar
 
 #.  Once the release is pushed to `PyPI`_, notify the issues mentioned on the new release of the new release.
     Example:

docs/styles/config/vocabularies/icalendar/accept.txt

@@ -27,6 +27,7 @@ src
 (?i)subcomponents?
 (?i)subpackages?
 subtyping
+towncrier
 (?i)Traceback
 (?i)unescaped
 uv

news/1244.documentation

@@ -0,0 +1 @@
+Replace the RFC quotations in the docstrings for :attr:`Alarm.REPEAT <icalendar.cal.alarm.Alarm.REPEAT>` and :attr:`Alarm.DURATION <icalendar.cal.alarm.Alarm.DURATION>` with Pythonic descriptions, including parameter notes, conformance references, and worked examples. @tmchow

news/1256.deps

@@ -0,0 +1 @@
+Added `towncrier <https://pypi.org/project/towncrier/>`_ to development dependencies. @stevepiercy

news/1256.documentation

@@ -0,0 +1 @@
+Edited contributor documentation for how to add a change log entry, and maintenance documentation for how to process news fragments. @stevepiercy

news/1256.internal

@@ -0,0 +1 @@
+Switched from manual change log management to `towncrier <https://pypi.org/project/towncrier/>`_ to automate the process. @stevepiercy

news/1349.bugfix

@@ -0,0 +1 @@
+Strictly validate BINARY property values in :attr:`vBinary.from_ical() <icalendar.prop.binary.vBinary.from_ical>` and reject malformed Base64 input instead of silently accepting invalid characters. @uwezkhan

news/1360.feature

@@ -0,0 +1 @@
+Created a :meth:`~icalendar.prop.recur.weekday.vWeekday.ical_value` property for the :class:`~icalendar.prop.recur.weekday.vWeekday` component, mirroring the existing pattern on :class:`~icalendar.prop.boolean.vBoolean`. @mvanhorn

news/1383.internal

@@ -0,0 +1 @@
+Bump PyPy from 3.10 to 3.11 for testing. @stevepiercy

news/876.feature

@@ -0,0 +1 @@
+Created an :attr:`~icalendar.prop.dt.period.vPeriod.ical_value` property for the :class:`~icalendar.prop.dt.period.vPeriod` component. @ZairKSM

pyproject.toml

@@ -100,6 +100,7 @@ dev = [
   {include-group = "test"},
   {include-group = "docs"},
   {include-group = "formatting"},
+  "towncrier>=25.8.0",
   "tox",
   "tox-uv",
 ]
@@ -301,6 +302,57 @@ filterwarnings = [
     "ignore::DeprecationWarning",
 ]
 
+[tool.towncrier]
+directory = "news/"
+filename = "CHANGES.rst"
+issue_format = "`Issue #{issue} <https://github.com/collective/icalendar/issues/{issue}>`_"
+start_string = ".. towncrier release notes start\n"
+title_format = "{version} ({project_date})"
+# First underline is used for version/date header.
+# Second underline is used for the type names (like 'Bug fixes:').
+underlines = ["-", "~", "`"]
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking changes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removal"
+name = "Removals and deprecations"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "New features"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "Bug fixes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "documentation"
+name = "Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deps"
+name = "Dependency changes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "internal"
+name = "Internal changes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "chore"
+name = "Other tasks"
+showcontent = false
+
+
 [tool.uv]
 python-preference = "managed"