docs: improve changelog to be automatically generated by towncrier (#921

)

docs/.gitignore

@@ -1,4 +1,3 @@
 /_build/
 /*.inc
 /license.rst
-/release_notes.rst

docs/conf.py

@@ -51,7 +51,7 @@
 
 language = "en"
 
-exclude_patterns = ["release_notes/*.*"]
+exclude_patterns = ["release_notes/*.*", "news.d/*.*"]
 
 todo_include_todos = False
 

docs/contributing.rst

@@ -189,26 +189,38 @@ A full list of test environments can be seen by issuing the following command:
 Making releases
 ~~~~~~~~~~~~~~~
 
+.. IMPORTANT::
+  Reference :ref:`release_notes_instructions` for creating relevant news fragments that will be added to the :ref:`release_notes`.
+
 Releases are automatically made by GitHub Actions on any ``master`` commit which is tagged.
 
 To create a new tagged release commit:
 
-- Create corresponding release notes in ``docs/release_notes/X.Y.Z.rst``.
-   - The release notes files in ``docs/release_notes/`` are used to
-     automatically generate the :ref:`release notes <release_notes>`.
+- Build the docs and review the content of ``docs/news.inc``.
+
+  - If necessary, create additional news files and build the docs again.
+
+- Add the news summary as the release notes and remove news fragments:
+
+  .. code-block::python
+
+     mv docs/news.inc docs/release_notes/X.Y.Z.rst
+     git add docs/release_notes/X.Y.Z.rst
+     git rm -f docs/news.d/*.rst
+
 - Execute ``python tools/release.py create X.Y.Z``.
-   - Will make commit with the new ``about.py`` version and release notes and tag it.
-   - Will make another commit setting ``about.py`` to the next pre release candidate version.
+   - Will make and tag a commit with the new ``about.py`` version, the release notes and removed news files.
+   - Will make another commit setting ``about.py`` to the next development version.
+
 - Push the tag to remote to trigger the release build.
-   -  ``git push origin vX.Y.Z``
-- If the release build is successful, you can push the two commits to master.
-   -  ``git push origin master``
-   - If, in the meantime, a new commit has come into origin/master the two
-     commits have to be merged into origin/master.
+   - ``git push origin vX.Y.Z``
 
+- If the release build is successful, you can push the two commits to master.
+   - ``git push origin master``
+   - If, in the meantime, a new commit has come into origin/master the two commits have to be merged into origin/master.
 
-The CI service makes a release by uploading a new package to PyPI when a tag
-named ``vX.Y.Z`` is found in Git. A new release will not be made if:
+The CI service makes a release by uploading a new package to PyPI when a tag named ``vX.Y.Z`` is found in Git.
+A new release will not be made if:
 
 - The ``X.Y.Z`` release is already on PyPI.
 - The repo tag does not exist.
@@ -222,3 +234,31 @@ Therefore, when bumping the submodules, maintainers/contributors need to remembe
 version.
 
 Furthermore, since OSVVM is tagged periodically, bumping from tag to tag is strongly suggested.
+
+.. _release_notes_instructions:
+
+Release Notes Instructions
+--------------------------
+
+The :vunit_file:`release notes directory <docs/news.d>` contains "newsfragments" which
+are short (`reST formatted
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_) files that
+contain information for users.
+
+Make sure to use full sentences in the **past or present tense** and use punctuation.
+
+Each file should be named like ``<issue #>.<type>.rst``, where ``<issue #>`` is the
+GitHub issue or pull request number, and ``<type>`` is one of:
+
+* ``breaking``: a change which may break existing functionality, such as feature removal
+  or behavior change
+* ``bugfix``: fixes a bug
+* ``change``: backwards compatible features or improvements
+* ``deprecation``: feature deprecation
+* ``misc``: a ticket was closed, but it is not necessarily important for the user
+
+For example: ``123.feature.rst``, ``456.bugfix.rst``.
+
+``towncrier`` preserves multiple paragraphs and formatting
+(code blocks, lists, and so on), but for entries other than features, it is usually
+better to stick to a single paragraph to keep it concise.

docs/news.d/921.misc.rst

@@ -0,0 +1,2 @@
+Improved release notes by adding sections to aid in finding relevant information
+about releases and updated contributing guide with instructions.

docs/release_notes.rst

@@ -0,0 +1,13 @@
+.. _release_notes:
+
+Release notes
+=============
+
+.. NOTE:: For installation instructions read :ref:`this <installing>`.
+
+:vunit_commit:`Next <master>`
+-----------------------------
+
+.. include:: news.inc
+
+.. include:: release_notes.inc

pyproject.toml

@@ -8,6 +8,44 @@ build-backend = "setuptools.build_meta"
 [tool.black]
 line-length = 120
 
+[tool.towncrier]
+package = "vunit"
+package_dir = "vunit"
+single_file = false
+filename="docs/news.inc"
+directory = "docs/news.d/"
+title_format = false
+issue_format = ":vunit_issue:`{issue}`"
+underlines = ["-", "~"]
+
+    [[tool.towncrier.section]]
+    path = ""
+
+    [[tool.towncrier.type]]
+    directory = "breaking"
+    name = "Breaking Changes"
+    showcontent = true
+
+    [[tool.towncrier.type]]
+    directory = "bugfix"
+    name = "Bug Fixes"
+    showcontent = true
+
+    [[tool.towncrier.type]]
+    directory = "change"
+    name = "Changes"
+    showcontent = true
+
+    [[tool.towncrier.type]]
+    directory = "deprecation"
+    name = "Deprecations"
+    showcontent = true
+
+    [[tool.towncrier.type]]
+    directory = "misc"
+    name = "Miscellaneous"
+    showcontent = true
+
 [tool.tox]
 legacy_tox_ini = """
 [tox]
@@ -34,6 +72,7 @@ deps=
     docs: furo
     docs: sphinx
     docs: sphinx-argparse
+    docs: towncrier
 
 setenv=
     acceptance-activehdl:  VUNIT_SIMULATOR=activehdl

tools/create_release_notes.py

@@ -11,7 +11,7 @@
 from pathlib import Path
 from os.path import relpath
 from glob import glob
-from subprocess import check_output, CalledProcessError
+from subprocess import check_call, check_output, CalledProcessError
 from shutil import which
 import datetime
 
@@ -33,22 +33,15 @@ def create_release_notes():
     """
     source_path = Path(__file__).parent.parent / "docs"
 
+    check_call(["towncrier", "build", "--keep"], cwd=source_path.parent)
+
     releases = get_releases(source_path)
     latest_release = releases[0]
 
-    with (source_path / "release_notes.rst").open("w", encoding="utf-8") as fptr:
+    with (source_path / "release_notes.inc").open("w", encoding="utf-8") as fptr:
         fptr.write(
-            f"""
-.. _release_notes:
-
-Release notes
-=============
-
-.. NOTE:: For installation instructions read :ref:`this <installing>`.
-
-`Commits since last release <https://github.com/VUnit/vunit/compare/{latest_release.tag!s}...master>`__
-
-"""
+            "`Commits since last release "
+            f"<https://github.com/VUnit/vunit/compare/{latest_release.tag!s}...master>`__"
         )
 
         fptr.write("\n\n")