Merge pull request #717 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@v3
+      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

.pre-commit-config.yaml

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

CHANGELOG.md

@@ -2,7 +2,11 @@
 This file documents all changes to Argus. This file is primarily meant to be
 read by developers.
 
-## [Unreleased]
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+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 -->
 
 ### Added
 - Added the possibility to filter incident by a given list of ids

README.md

@@ -226,3 +226,42 @@ $ tox
 ```
 An [HTML coverage report](htmlcov/index.html) will be generated.
 Refer to the [tox.ini](tox.ini) file for further options.
+
+## Using towncrier to automatically produce the changelog
+### Before opening a PR
+To be able to automatically produce the changelog for a release a file for each
+pull request (also called news fragment) needs to be added to the folder
+`changelog.d/`.
+The name of the file consists of three parts seperated by a period:
+1. The identifier, either the issue number this pull request is refering to or if
+there is no related issue a `+` followed by a unique short description.
+2. The type of the change, we use `critical`, `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 linked to an issue would be `214.added.md` or for a file
+without corresponding issue `+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 one can use towncrier to create such a file as following:
+
+```console
+$ towncrier create -c "Changelog content" 214.added.md
+```
+
+When opening a PR there will be a check to make sure that a news fragment is added, it
+will fail if it is missing.
+
+### Before a release
+To add all content from the `changelog.d/` folder to the changelog file simply run
+```console
+$ towncrier build --version {version}
+```
+This will also delete all files in `changelog.d/`.
+
+To preview what the addition to the changelog file would look like add the flag `--draft`.
+
+A few other helpful flags:
+- `date DATE` - set the date of the release, default is today
+- `keep` - keep all news fragments
+
+More information about [towncrier](https://towncrier.readthedocs.io).

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

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

pyproject.toml

@@ -60,6 +60,7 @@ dev = [
     "ipython",
     "pre-commit",
     "python-dotenv",
+    "towncrier",
     "werkzeug",
     "tox<4",  # does not work on tox 4 for some reason
     "build",  # for debugging builds/installs
@@ -106,3 +107,32 @@ exclude = '''
   | src/.*/migrations
 )
 '''
+
+[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/Argus/issues/{issue})"
+wrap = true
+
+[[tool.towncrier.type]]
+directory = "critical"
+name = "Critical"
+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