Improved changelog to be automatically managed by towncrier

.gitignore

@@ -17,7 +17,7 @@ my_logger.csv
 /docs/_build
 /docs/_theme
 /docs/license.rst
-/docs/release_notes.rst
+/docs/theme.tgz
 /examples/vhdl/array_axis_vcs/src/test/data/out.csv
 /tests/acceptance/*_out
 /tests/unit/test_report_output.txt

docs/changelog.d/.gitignore

@@ -0,0 +1,3 @@
+*
+!*.*.rst
+!template.rst.j2

docs/changelog.d/881.misc.rst

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

docs/changelog.d/template.rst.j2

@@ -0,0 +1,37 @@
+{% for section, _ in sections.items() %}
+
+{% set underline = underlines[0] %}{% if section %}{{section}}
+{{ underline * section|length }}{% set underline = underlines[1] %}
+
+{% endif %}
+
+`Download from PyPI <https://pypi.python.org/pypi/vunit_hdl/{{version}}/>`_ | `Commits since this release <https://github.com/VUnit/vunit/compare/v{{version}}...master>`_
+
+{% 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() %}
+- {{ text }}
+  {{ values|join(',\n  ') }}
+{% 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 %}

docs/conf.py

@@ -20,6 +20,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinxarg.ext",  # Automatic argparse command line argument documentation
+    "sphinxcontrib.towncrier.ext",
     "exec",
 ]
 
@@ -45,7 +46,7 @@
 
 language = "en"
 
-exclude_patterns = ["release_notes/*.*"]
+exclude_patterns = ["changelog.d/**"]  # towncrier manages changelog
 
 pygments_style = "sphinx"
 
@@ -89,6 +90,11 @@
     "pytest": ("https://docs.pytest.org/en/latest/", None),
 }
 
+# -- Towncrier draft ------------------------------------------------------
+towncrier_draft_autoversion_mode = "draft"
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = ROOT.parent
+
 # -- ExtLinks -------------------------------------------------------------
 
 extlinks = {

docs/contributing.rst

@@ -193,9 +193,8 @@ Releases are automatically made by GitHub Actions on any ``master`` commit which
 
 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>`.
+- Reference :ref:`release_notes_instructions` for creating relevant news that will be
+  added to the final draft of the :ref:`release_notes`.
 - 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.
@@ -222,3 +221,37 @@ 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/changelog.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.
+
+The Tox ``*-docs`` environment will construct a draft, "unreleased" section in the
+generated HTML page to make it easier to debug and fix syntax issues with the
+newsfragments. During a release, towncrier will add the latest
+:vunit_file:`newsfragments <docs/changelog.d>` to the :ref:`release_notes` and then
+remove the newsfragments from version control.