activate towncrier

.github/PULL_REQUEST_TEMPLATE.md

@@ -16,7 +16,8 @@ A few sentences and/or a bulleted list to describe and motivate the change:
 - [ ] docstring updated (if appropriate),
 - [ ] update user guide (if appropriate),
 - [ ] added tests,
-- [ ] added line to CHANGELOG.rst,
+- [ ] add a changelog entry in the `upcoming_changes` folder (see [`upcoming_changes/README.rst`](https://github.com/lumispy/lumispy/blob/main/upcoming_changes/README.rst)),
+- [ ] Check formatting of the changelog entry (and eventual user guide changes) in the `docs/readthedocs.org:lumispy` build of this PR (link in github checks),
 - [ ] ready for review.
 
 ### Minimal example of the bug fix or the new feature

.readthedocs.yaml

@@ -10,6 +10,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  jobs:
+    post_checkout:
+      - git fetch --unshallow || true
 
 ## Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -20,9 +23,9 @@ formats: all
 
 
 python:
-   install:
-      - method: pip
-        path: .
-        extra_requirements:
-           - build-doc
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
 

doc/conf.py

@@ -27,6 +27,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.graphviz",
     "sphinx.ext.autosummary",
+    "sphinxcontrib.towncrier",
     "sphinx_copybutton",
 ]
 
@@ -109,3 +110,11 @@ def setup(app):
     app.connect("builder-inited", run_apidoc)
     app.add_css_file("css/dark.css")
     app.add_css_file("css/light.css")
+
+
+# -- Options for towncrier_draft extension -----------------------------------
+
+# Options: draft/sphinx-version/sphinx-release
+towncrier_draft_autoversion_mode = "draft"
+towncrier_draft_include_empty = False
+towncrier_draft_working_directory = ".."

prepare_release.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+import argparse
+import re
+import subprocess
+
+
+def run_towncrier(tag):
+    cmd = ("towncrier", "build", "--version", tag.strip("v"))
+
+    return subprocess.call(cmd)
+
+
+def update_fallback_version_in_pyproject(tag, fname="pyproject.toml"):
+    version = tag.strip("v").split(".")
+    # Default to +1 on minor version
+    major, minor = version[0], int(version[1]) + 1
+
+    with open(fname, "r") as file:
+        lines = file.readlines()
+
+    pattern = "fallback_version"
+    new_version = f"{major}.{minor}.dev0"
+    # Iterate through the lines and find the pattern
+    for i, line in enumerate(lines):
+        if re.search(pattern, line):
+            lines[i] = f'{pattern} = "{new_version}"\n'
+            break
+
+    # Write the updated content back to the file
+    with open(fname, "w") as file:
+        file.writelines(lines)
+
+    print(
+        f"\nNew (fallback) dev version ({new_version}) written to `pyproject.toml`.\n"
+    )
+
+
+if __name__ == "__main__":
+    # Get tag argument
+    parser = argparse.ArgumentParser()
+    parser.add_argument("tag")
+    args = parser.parse_args()
+    tag = args.tag
+
+    # Update release notes
+    run_towncrier(tag)
+
+    # Update fallback version for setuptools_scm
+    update_fallback_version_in_pyproject(tag)

pyproject.toml

@@ -79,6 +79,8 @@ doc = [
   "sphinx>=4.3.0",
   "sphinx_rtd_theme>=0.5.1",
   "sphinx-copybutton",
+  "sphinxcontrib-towncrier",
+  "towncrier",
 ]
 dev = [
   "black",
@@ -130,3 +132,19 @@ include = ["lumispy*"]
 # Presence enables setuptools_scm, the version will be determined at build time from git
 # The version will be updated by the `prepare_release.py` script
 fallback_version = "0.3.dev0"
+
+[tool.towncrier]
+directory = "upcoming_changes/"
+filename = "CHANGES.rst"
+issue_format = "`#{issue} <https://github.com/hyperspy/holospy/issues/{issue}>`_"
+title_format = "{version} ({project_date})"
+package_dir = "holospy"
+type = [
+    { directory = "new", name = "New features", showcontent = true },
+    { directory = "enhancements", name = "Enhancements", showcontent = true },
+    { directory = "bugfix", name = "Bug Fixes", showcontent = true },
+    { directory = "api", name = "API changes", showcontent = true },
+    { directory = "deprecation", name = "Deprecations", showcontent = true },
+    { directory = "doc", name = "Improved Documentation", showcontent = true },
+    { directory = "maintenance", name = "Maintenance", showcontent = true },
+]

releasing_guide.md

@@ -5,17 +5,19 @@ To publish a new LumiSpy release do the following steps:
 ## Preparation
 
 - Create a new PR to the 'main' branch for the release process, e.g. `release_v0.1.1`
-- Make sure to have the code ready, including changelog
-- Set the correct version number in `lumispy/release_info.py` (increase the third 
-  digit for a patch release, the second digit for a regular minor release, the
-  first digit for a major release)
+- In a pull request, prepare the release by running the `prepare_release.py` python script
+  (e.g. `python prepare_release.py 0.1.1`), which will do the following:
+  - update the release notes in `CHANGES.rst` by running `towncrier`,
+  - update the `setuptools_scm` fallback version in `pyproject.toml` (for a patch release, this will stay the same).
+- Check release notes
 - Let that PR collect comments for a day to ensure that other maintainers are comfortable 
   with releasing
 - Set correct date and version number in `CHANGELOG.rst`
 
 ## Tag and Release
 
-- Create a tag e.g. `git tag -a v0.1.1 -m "LumiSpy version 0.1.1"`
+- Create a tag e.g. `git tag -a v0.1.1 -m "LumiSpy version 0.1.1"`. The lumispy version will
+  be set at build time from the tag by `setuptools_scm`.
 - Push tag to user fork for a test run `git push origin v0.1.1`. Will run the release
   workflow without uploading to PyPi
 - Push tag to LumiSpy repository to trigger release `git push upstream v0.1.1`
@@ -24,8 +26,6 @@ To publish a new LumiSpy release do the following steps:
 
 ## Post-release action
 
-- Increment the version and set it back to dev: `vx.y.zdev0`
-- Update version in other branches if necessary
 - Prepare `CHANGELOG.rst` for development by adding `UNRELEASED` headline
 - Merge the PR
 

upcoming_changes/README.rst

@@ -0,0 +1,36 @@
+This directory contains "news fragments" which are short files that contain a small **ReST**-formatted
+text that will be added to the next ``CHANGELOG``.
+
+The ``CHANGELOG`` will be read by **users**, so this description should be aimed to LumiSpy users
+instead of describing internal changes which are only relevant to the developers.
+
+Each file should be named like ``<ISSUE>.<TYPE>.rst``, where
+``<ISSUE>`` is an issue number, and ``<TYPE>`` is one of:
+
+* ``new``: new user facing features, like new command-line options and new behavior.
+* ``enhancements``: improvement of existing functionality, usually without requiring user intervention.
+* ``bugfix``: fixes a bug.
+* ``api``: a change which may break an existing script, such as feature removal or behavior change.
+* ``deprecation``: feature deprecation.
+* ``doc``: documentation improvement, like rewording an entire session or adding missing docs.
+* ``maintenance``: a change related to the test suite, packaging, etc.
+
+So for example ``141.new.rst`` or ``273.bugfix.rst``.
+
+If your PR fixes an issue, use the number of the issue here. If there is no issue,
+then after you submit the PR and get the PR number you can add a
+changelog using that instead.
+
+If you are not sure what issue type to use, don't hesitate to ask in your PR.
+
+``towncrier`` preserves multiple paragraphs and formatting (code blocks, lists, and so on), but for entries
+other than ``new`` it is usually better to stick to a single paragraph to keep it concise. For ``new``,
+it is recommended to add a hyperlink to the user guide.
+
+To make a draft of the changelog, run from the command line:
+
+   .. code-block:: bash
+
+       $ towncrier build --draft
+
+See https://github.com/twisted/towncrier for more details.