From edbaeaae44fc5d331ac2642420725e511e9e1be3 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Fri, 1 Dec 2023 19:54:03 +0100 Subject: [PATCH] Use towncrier to manage release notes --- .github/PULL_REQUEST_TEMPLATE.md | 3 +- .gitignore | 1 + .readthedocs.yaml | 13 +++++---- CHANGES.rst | 8 +++-- doc/conf.py | 15 ++++++++++ prepare_release.py | 49 +++++++++++++++++++++++++++++++ pyproject.toml | 50 +++++++++++++++++++++++++++++++- releasing_guide.md | 8 ++--- 8 files changed, 133 insertions(+), 14 deletions(-) create mode 100644 prepare_release.py diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9dadaa450..4afe44428 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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 CHANGES.rst, +- [ ] add a changelog entry in the `upcoming_changes` folder (see [`upcoming_changes/README.rst`](https://github.com/hyperspy/exspy/blob/main/upcoming_changes/README.rst)), +- [ ] Check formatting of the changelog entry (and eventual user guide changes) in the `docs/readthedocs.org:exspy` build of this PR (link in github checks) - [ ] ready for review. ### Minimal example of the bug fix or the new feature diff --git a/.gitignore b/.gitignore index ccb49562c..9b2aef230 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ doc/_build/* doc/auto_examples/* +doc/sg_execution_times.rst build/* dist/* *egg-info* diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 015d38882..f11b9ac62 100644 --- a/.readthedocs.yaml +++ b/.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,8 +23,8 @@ formats: - htmlzip python: - install: - - method: pip - path: . - extra_requirements: - - doc + install: + - method: pip + path: . + extra_requirements: + - doc diff --git a/CHANGES.rst b/CHANGES.rst index 97ecc327c..3012caab3 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -2,10 +2,12 @@ Changelog ********* Changelog entries for the development version are available at -https://holospy.readthedocs.io/en/latest/changes.html +https://exspy.readthedocs.io/en/latest/changes.html -0.1.dev0 (UNRELEASED) -===================== + +.. towncrier-draft-entries:: |release| [UNRELEASED] + +.. towncrier release notes start - Enable ``signal_range`` arguments when using ``subpixel=True`` in :py:meth:`~.signals.EELSSpectrum.align_zero_loss_peak` (`#7 `_) - Support for tabulated :ref:`Generalised Oscillator Strengths (GOS) ` using the diff --git a/doc/conf.py b/doc/conf.py index 7c4ea7c78..7f459f6fa 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,9 +14,16 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) +import hyperspy.api as hs +import logging import numpydoc from packaging.version import Version + +# Set logging level to `ERROR` to avoid exspy warning in documentation +hs.set_log_level("ERROR") + + # -- Project information ----------------------------------------------------- project = "exSpy" @@ -42,6 +49,7 @@ "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "sphinx_gallery.gen_gallery", + "sphinxcontrib.towncrier", ] linkcheck_ignore = [ @@ -147,3 +155,10 @@ copybutton_prompt_text = r">>> |\.\.\. " copybutton_prompt_is_regexp = True + +# -- 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 = ".." diff --git a/prepare_release.py b/prepare_release.py new file mode 100644 index 000000000..4fbef1f3a --- /dev/null +++ b/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) diff --git a/pyproject.toml b/pyproject.toml index 89b1fc936..ba616acc8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -68,6 +68,8 @@ file = "LICENSE" "sphinx-design", "sphinx-favicon", "sphinx-gallery", + "sphinxcontrib-towncrier", + "towncrier", ] "tests" = [ "pytest >= 5.0", @@ -96,7 +98,10 @@ force-exclude = ''' [tool.coverage.run] branch = true source = ["hyperspy"] -omit = ["hyperspy/tests/*"] +omit = [ + "hyperspy/tests/*", + "prepare_release.py", + ] [tool.coverage.report] precision = 2 @@ -120,3 +125,46 @@ include = ["exspy*"] # Presence enables setuptools_scm, the version will be determine at build time from git # The version will be updated by the `prepare_release.py` script fallback_version = "0.1.dev0" + + +[tool.towncrier] +package_dir = "exspy" +filename = "CHANGES.rst" +directory = "upcoming_changes/" +title_format = "{version} ({project_date})" +issue_format = "`#{issue} `_" + + [[tool.towncrier.type]] + directory = "new" + name = "New features" + showcontent = true + + [[tool.towncrier.type]] + directory = "bugfix" + name = "Bug Fixes" + showcontent = true + + [[tool.towncrier.type]] + directory = "doc" + name = "Improved Documentation" + showcontent = true + + [[tool.towncrier.type]] + directory = "deprecation" + name = "Deprecations" + showcontent = true + + [[tool.towncrier.type]] + directory = "enhancements" + name = "Enhancements" + showcontent = true + + [[tool.towncrier.type]] + directory = "api" + name = "API changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "maintenance" + name = "Maintenance" + showcontent = true diff --git a/releasing_guide.md b/releasing_guide.md index 2772d8175..2de718f81 100644 --- a/releasing_guide.md +++ b/releasing_guide.md @@ -4,10 +4,10 @@ To publish a new exSpy release do the following steps: ## Preparation -- Create a new PR to the 'main' branch for the release process, e.g. `release_v0.1.1` with - the following changes: - - Update and check release notes - - Update dev `fallback_version` in `pyproject.toml` +- In a pull request, prepare the release by running the `prepare_release.py` python script (e.g. `python prepare_release.py 0.2`) , 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 `CHANGES.rst`