Merge pull request #2869 from johannaengland/add-towncrier

 Add towncrier to produce changelog

.github/workflows/towncrier.yml

@@ -0,0 +1,19 @@
+name: Check for changelog file
+
+on: [pull_request]
+
+jobs:
+  towncrier:
+    runs-on: ubuntu-latest
+    name: Towncrier check
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Install towncrier
+      run: |
+        pip install -U pip
+        pip install towncrier
+    - name: Check for changelog file
+      run: towncrier check --compare-with origin/master

.gitignore

@@ -4,6 +4,7 @@
 *.swp
 *~
 .*
+!.gitkeep
 !.github/
 *.bak
 *.iml # JetBrains (PyCharm/IDEA) project files

.pre-commit-config.yaml

@@ -6,6 +6,7 @@ repos:
     -   id: trailing-whitespace
     -   id: mixed-line-ending
     -   id: end-of-file-fixer
+        exclude: &exclude_pattern '^changelog.d/'
 -   repo: https://github.com/pycqa/flake8
     rev: 3.9.2
     hooks:
@@ -17,3 +18,9 @@ repos:
     rev: 22.3.0
     hooks:
     -   id: black
+-   repo: https://github.com/twisted/towncrier
+    rev: 23.11.0
+    hooks:
+      - id: towncrier-check
+        files: $changelog\.d/
+        args: [--compare-with origin/master]

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This changelog format was introduced in NAV 5.4.0. Older changelogs can be
 found in the [HISTORY](HISTORY) file.
 
+This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/Uninett/Argus/tree/master/changelog.d/>.
+
+<!-- towncrier release notes start -->
+
 ## [Unreleased]
 
 ### Fixed

changelog.d/+towncrier-changelog.added.md

@@ -0,0 +1 @@
+Added towncrier to automatically produce changelog

doc/hacking/hacking.rst

@@ -104,6 +104,41 @@ contribute to NAV.
 
 .. _CLA assistant: https://cla-assistant.io/
 
+Adding a changelog entry
+------------------------
+
+We are using `towncrier`_ to automatically produce the changelog from separate files
+at the time of a release. These files can be found in the folder :file:`changelog.d/`.
+Every entry should explain what a change does in terms that are understandable for end
+users.
+
+When creating a pull request you should also add such a file.
+
+The name of the file consists of three parts separated by a period:
+
+1. The identifier: either the issue number (in case the pull request fixes that issue)
+   or the pull request number. If you don't want to add a link to the resulting
+   changelog entry then a + followed by a unique short description.
+2. The type of the change: we use security, removed, deprecated, added, changed and
+   fixed.
+3. The file suffix, e.g. .md, towncrier does not care which suffix a fragment has.
+
+So an example for a file name related to an issue/pull request would be
+:file:`214.added.md` or for a file without corresponding issue
+:file:`+fixed-pagination-bug.fixed.md`.
+
+This file can either be created manually with a file name as specified above and the
+changelog text as content or you can use towncrier to create such a file as following:
+
+.. code-block:: console
+
+   $ towncrier create -c "Changelog content" 214.added.md
+
+When opening a pull request there will be a check to make sure that a news fragment is
+added and it will fail if it is missing.
+
+.. _towncrier: https://towncrier.readthedocs.io/
+
 
 Directory layout
 ================

doc/hacking/release-procedure.rst

@@ -58,27 +58,36 @@ new release.
 Updating changelog and release notes
 ------------------------------------
 
-* Generate a list of referenced issues from the GitHub milestone::
+Towncrier can be used to automatically produce a changelog using the
+:file:`changelog.d` directory which contains files describing changes since the last release.
 
-    ./tools/buglog.py 4.8.3
+To add these changes to :file:`CHANGELOG.md` simply run
 
-  ``buglog`` depends on the ``github`` library, install with
-  ``pip install PyGithub``.
-  (`PyGithub documentation <https://pygithub.readthedocs.io/en/latest/>`_)
+.. code-block:: console
 
-* Add a new entry :file:`CHANGELOG.md` for for the new release and paste the
-  list produced by the above command. Sort items into types of changes
-  according to the principles of `Keep A Changelog
-  <https://keepachangelog.com/en/1.0.0/>`_, and optionally change item titles
-  to be more end-user friendly if need be.  Commit the changes::
+  $ towncrier build --version {version}
 
-    git commit -m 'Update changelog for the upcoming X.Y.Z release'
+This will also delete all files in :file:`changelog.d/`.
 
-* Bump and tag the version number (and sign the tag) using ``version.sh``, and
-  push the changes back to the official repository::
+To preview what the addition to the changelog file would look like add the flag
+``--draft``.
+A few other helpful flags are:
+* `date DATE` - set the date of the release, default is today
+* `keep` - keep all news fragments
+
+Commit the changes using
 
-    ./version.sh -t
-    git push --tags
+.. code-block:: console
+
+  $ git commit -m 'Update changelog for the upcoming X.Y.Z release'
+
+Bump and tag the version number (and sign the tag) using ``version.sh``, and
+push the changes back to the official repository:
+
+.. code-block:: console
+
+  $ ./version.sh -t
+  $ git push --tags
 
 
 Announcing the release

pyproject.toml

@@ -94,3 +94,42 @@ exclude = '''
   | python/nav/etc/geomap/config\.py  # Not actually a Python file
 )
 '''
+
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+start_string = "<!-- towncrier release notes start -->\n"
+underlines = ["", "", ""]
+title_format = "## [{version}] - {project_date}"
+issue_format = "[#{issue}](https://github.com/Uninett/nav/issues/{issue})"
+wrap = true
+
+[[tool.towncrier.type]]
+directory = "security"
+name = "Security"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true

requirements/optional.txt

@@ -1 +1,2 @@
 python-ldap==3.4.4 # optional for LDAP authentication, requires libldap (OpenLDAP) to build
+towncrier