Merge pull request #207 from cta-observatory/implement_towncrier

Implement towncrier

.github/workflows/ci.yml

@@ -1,10 +1,17 @@
 name: CI
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - '**'
+  pull_request:
 
 env:
   MPLBACKEND: Agg
   PYTEST_ADDOPTS: --color=yes
+  GITHUB_PR_NUMBER: ${{ github.event.number }}
 
 jobs:
   tests:
@@ -58,11 +65,15 @@ jobs:
       - name: Install doc dependencies
         run: |
           sudo apt update --yes && sudo apt install --yes git build-essential pandoc curl graphviz
-          pip install -U pip setuptools wheel
+          pip install -U pip setuptools wheel towncrier
           pip install -e .[docs]
           git describe --tags
           python -c 'import pyirf; print(pyirf.__version__)'
 
+      - name: Produce Changelog
+        run: |
+          towncrier build --yes
+
       - name: Build docs
         run: cd docs && make html SPHINXOPTS="-W --keep-going -n --color -j auto"
 
@@ -76,3 +87,19 @@ jobs:
           FOLDER: docs/_build/html
           CLEAN: true
           SINGLE_COMMIT: true
+
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set environment
+        run: echo FRAGMENT_NAME="docs/changes/${GITHUB_PR_NUMBER}.*.rst" >> $GITHUB_ENV
+
+      - name: Check for news fragment
+        uses: andstor/file-existence-action@v2
+        with: 
+          files: ${{ env.FRAGMENT_NAME }}
+          fail: true

docs/changes/180.feature.rst

@@ -0,0 +1,2 @@
+Add interpolation function for RAD_MAX tables. 
+There is now a ``interpolate_rad_max`` function in ``pyirf.interpolation`` that is a simple wrapper around ``scipy.interpolate.griddata``.

docs/changes/200.bugfix.rst

@@ -0,0 +1 @@
+Units are now correctly handled in ``pyirf.spectral.PowerLaw``.

docs/changes/202.maintenance.rst

@@ -0,0 +1 @@
+Updates ``gammapy`` dependency to version 1.

docs/changes/207.maintenance.rst

@@ -0,0 +1 @@
+Add and enable ``towncrier`` in CI.

docs/changes/README.md

@@ -0,0 +1,21 @@
+# How to use `towncrier`
+
+A tutorial can be found [here](https://towncrier.readthedocs.io/en/stable/tutorial.html). 
+
+1. Create a new file for your changes `<PULL REQUEST>.<TYPE>.rst` in the corresponding folder. The following types are available:
+    - feature: `New feature`
+    - bugfix: `Bugfix`
+    - api: `API Changes`
+    - optimization: `Refactoring and Optimization`
+    - maintenance: `Maintenance`
+
+2. Write a suitable message for the change:
+    ```
+    Fixed ``crazy_function`` to be consistent with ``not_so_crazy_function``
+    ```
+
+3. (For maintainers) How to generate a change log:
+    - Execute the following command in the base directory of the project
+    ```
+    towncrier build --version=<VERSION NUMBER>
+    ```

docs/changes/template.rst

@@ -0,0 +1,43 @@
+{% if render_title %}
+{% if versiondata.name %}
+{{ versiondata.name }} {{ versiondata.version }} ({{ versiondata.date }})
+{{ top_underline * ((versiondata.name + versiondata.version + versiondata.date)|length + 4)}}
+{% else %}
+{{ versiondata.version }} ({{ versiondata.date }})
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 3)}}
+{% endif %}
+{% endif %}
+
+{% for category, val in definitions.items() %}
+
+{% set underline = underlines[0] %}
+{{ definitions[category]['name'] }}
+{{ underline * definitions[category]['name']|length }}
+{% set underline = underlines[1] %}
+
+{% for section, _ in sections.items() %}
+{% if section and category in sections[section] %}
+{{section}}
+{{ underline * section|length }}
+
+{% endif %}
+{% if sections[section] and category in sections[section] %}
+{% if definitions[category]['showcontent'] %}
+{% for text, values in sections[section][category].items() %}
+- {{ text }} [{{ values|join(', ') }}]
+
+{% endfor %}
+{% else %}
+- {{ sections[section][category]['']|join(', ') }}
+
+{% endif %}
+{% if sections[section][category]|length == 0 %}
+No significant changes.
+
+{% else %}
+{% endif %}
+{% else %}
+{# No significant changes. #}
+{% endif %}
+{% endfor %}
+{% endfor %}

docs/conf.py

@@ -72,7 +72,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "changes"]
 
 
 # -- Options for HTML output -------------------------------------------------

docs/contribute.rst

@@ -44,6 +44,10 @@ See the `GitHub tutorial on forks <https://docs.github.com/en/github/getting-sta
      that the test is then passing.
      This helps understanding the bug and will prevent it from reappearing later.
 
+   - Create a changelog entry in ``docs/changes``, please note the ``README.md`` there.
+     Minor changes (on the magnitude of fixing a broken link or renaming a variable) can receive the ``no-changelog-needed`` label. 
+     This should, however, be a rare exception.    
+
 #. Wait for review comments and then implement or discuss requested changes.
 
 

environment.yml

@@ -17,6 +17,7 @@ dependencies:
   - pytest
   - pytest-cov
   # docs
+  - towncrier
   - numpydoc
   - pytables
   - nbsphinx

pyproject.toml

@@ -1,3 +1,35 @@
 [build-system]
 requires = ["setuptools >= 40.6.0", "setuptools_scm[toml]>=3.4"]
 build-backend = "setuptools.build_meta"
+
+[tool.towncrier]
+    package = "pyirf"
+    directory = "docs/changes"
+    filename = "CHANGES.rst"
+    template = "docs/changes/template.rst"
+    # let towncrier create proper links to the merged PR
+    issue_format = "`#{issue} <https://github.com/cta-observatory/pyirf/pull/{issue}>`__"
+
+    [tool.towncrier.fragment.feature]
+        name = "New Features"
+        showcontent = true
+
+    [tool.towncrier.fragment.bugfix]
+        name = "Bug Fixes"
+        showcontent = true
+
+    [tool.towncrier.fragment.api]
+        name = "API Changes"
+        showcontent = true
+
+    [tool.towncrier.fragment.optimization]
+        name = "Refactoring and Optimization"
+        showcontent = true
+
+    [tool.towncrier.fragment.maintenance]
+        name = "Maintenance"
+        showcontent = true
+
+    [[tool.towncrier.section]]
+        name = ""
+        path = ""