Improved changelog to be automatically managed by towncrier

.github/workflows/push.yml

@@ -1,6 +1,8 @@
 name: 'push'
 
 on:
+  label:
+    types: [created, edited]
   push:
   pull_request:
   schedule:
@@ -137,13 +139,55 @@ jobs:
     - name: '🚧 Run job'
       run: tox -e py${{ matrix.task }} -- --color=yes
 
+#
+# Release Notes (News) Validation
+#
+  news-matrix-prep:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+    steps:
+      - id: set-matrix
+        run: |
+          set -e
+
+          cat <<EOF > json
+          ${{ toJSON(github.event.pull_request.labels.*.name) }}
+          EOF
+
+          eval "news_labels=( $(jq '.[] | select(test("news:"))' json) )"
+          news_labels_json=$(jq --compact-output --null-input '$ARGS.positional' --args -- "${news_labels[@]}")
+
+          echo "Setting matrix to labels: ${news_labels[@]}"
+          echo "Matrix labels JSON: $news_labels_json"
+          echo "matrix={\"news\":$(echo $news_labels_json)}" >> $GITHUB_OUTPUT
+
+  news:
+    runs-on: ubuntu-latest
+    needs: news-matrix-prep
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.news-matrix-prep.outputs.matrix) }}
+    name: '📰 Validate News · ${{ matrix.news }}'
+    steps:
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v3
+
+    - name: News file exists
+      run: |
+        fname="$(echo ${{ github.event.pull_request.number }}.${{ matrix.news }}.rst | sed 's,news:,,g')"
+        news_file="docs/news.d/$fname"
+        echo "News file that must exist for the label '${{ matrix.news }}': '$news_file'"
+        test -f $news_file
+
 #
 # Deploy to PyPI
 #
 
   deploy:
     runs-on: ubuntu-latest
-    needs: [ fmt, lin, docker, win ]
+    needs: [ fmt, lin, docker, win, news ]
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
     name: '🚀 Deploy'
     steps:

.gitignore

@@ -15,10 +15,12 @@ my_logger.csv
 /build/
 /dist/
 /docs/_build
+/docs/_release_notes_draft.rst
 /docs/_theme
 /docs/license.rst
-/docs/release_notes.rst
+/docs/theme.tgz
 /examples/vhdl/array_axis_vcs/src/test/data/out.csv
+/release/
 /tests/acceptance/*_out
 /tests/unit/test_report_output.txt
 /vunit/vhdl/check/test/tb_check_equal.vhd

docs/conf.py

@@ -45,7 +45,7 @@
 
 language = "en"
 
-exclude_patterns = ["release_notes/*.*"]
+exclude_patterns = ["news.d/**"]  # towncrier manages changelog
 
 pygments_style = "sphinx"
 

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/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.
+
+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/news.d>` to the :ref:`release_notes` and then remove
+the newsfragments from version control.

docs/news.d/.gitignore

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

docs/news.d/885.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/news.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/{{versiondata["version"]}}/>`__ | `Commits since this release <https://github.com/VUnit/vunit/compare/v{{versiondata["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 %}