Add pseudo auto-generated notes for the 2.x+ release branch

.pre-commit-config.yaml

@@ -4,8 +4,9 @@ repos:
     hooks:
     -   id: check-yaml
     -   id: end-of-file-fixer
+        exclude: ^(doc/source/releases.md)
     -   id: trailing-whitespace
-        exclude: ^.*\.(pdb)$
+        exclude: ^(.*\.(pdb)|doc/source/releases.md)$
 -   repo: https://github.com/pycqa/isort
     rev: 5.12.0
     hooks:

doc/source/conf.py

@@ -84,6 +84,7 @@ def sort_authors(filename):
     "sphinxcontrib.bibtex",
     "matplotlib.sphinxext.plot_directive",
     "mdanalysis_sphinx_theme",
+    "myst_parser",
 ]
 
 bibtex_bibfiles = ["references.bib"]

doc/source/index.rst

@@ -73,6 +73,7 @@ Wherever possible, do not take these conversations to private channels, includin
    examples/quickstart
    faq
    examples/README
+   releases
 
 .. toctree::
    :maxdepth: 1

doc/source/preparing_releases_and_hotfixes.rst

@@ -176,6 +176,13 @@ Create a release of the UserGuide
 
 For now, the UserGuide is released at the same time as the core library. To make a release of the UserGuide you should:
 
+#. Make a Pull Request with a re-generated ``releases.md`` which contains a copy of the GitHub release notes. This can be generated by doing:
+
+    .. code-block:: bash
+
+        cd doc/source/scripts
+        python gen_release_notes.py
+
 #. Create a new release tag and upload them for the UserGuide repository.
 
     .. code-block:: bash

doc/source/scripts/gen_release_notes.py

@@ -0,0 +1,48 @@
+import os
+import pathlib
+import re
+
+from github import Github
+
+
+def gen_release_notes(filename):
+    git = Github(os.environ["GITHUB_TOKEN"])
+    repo = git.get_repo("MDAnalysis/mdanalysis")
+    releases = repo.get_releases()
+
+    parent_directory = pathlib.Path(__file__).parent.parent
+    parent_directory.mkdir(exist_ok=True, parents=True)
+    filename = parent_directory / filename
+
+    filetext = "# MDAnalysis Release Notes\n\n\n"
+
+    # Should be ordered
+    for release in repo.get_releases():
+        # MDAnalysis releases always follow a tag pattern of *-release_version
+        version = release.tag_name.split("-")[1]
+
+        # Only write out version 2.x+ since those are the only ones that
+        # we can guarantee similarly written notes for
+        if int(version.split(".")[0]) < 2:
+            continue
+
+        if release.body.startswith("###"):
+            filetext += release.body[1:]
+        else:
+            filetext += release.body
+
+        filetext += "\n\n"
+
+    # replace all @ starting handles with github links
+    # \b doesn't work so we're using \s and getting extra whitespace
+    handles = set(re.findall(r"\s@\w+", filetext))
+    for entry in handles:
+        new_word = f" [{entry[1:]}](https://github.com/{entry[2:]})"
+        filetext = filetext.replace(entry, new_word)
+
+    with open(filename, "w") as f:
+        f.write(filetext)
+
+
+if __name__ == "__main__":
+    gen_release_notes("releases.md")

environment.yml

@@ -22,6 +22,7 @@ dependencies:
   - ipython
   - ipywidgets<8.0.0
   - jupyter_contrib_nbextensions
+  - myst-parser
   - nbconvert # not called by any notebook explicitly but to download notebooks, or in nbsphinx
   - nbformat
   - nbsphinx