Merge pull request #54 from tangkong/doc_prerelease_notes

DOC: add prerelease notes to cookiecutter

{{ cookiecutter.folder_name }}/.github/PULL_REQUEST_TEMPLATE.md

@@ -27,3 +27,5 @@
 - [ ] New/changed functions and methods are covered in the test suite where possible
 - [ ] Test suite passes locally
 - [ ] Test suite passes on GitHub Actions
+- [ ] Ran ``docs/pre-release-notes.sh`` and created a pre-release documentation page
+- [ ] Pre-release docs include context, functional descriptions, and contributors as appropriate

{{ cookiecutter.folder_name }}/.pre-commit-config.yaml

@@ -28,6 +28,6 @@ repos:
     -   id: flake8
 
 -   repo: https://github.com/timothycrosley/isort
-    rev: 5.11.4
+    rev: 5.13.2
     hooks:
     -   id: isort

{{ cookiecutter.folder_name }}/docs/pre-release-notes.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+ISSUE=$1
+shift
+DESCRIPTION=$*
+
+if [[ -z "$ISSUE" || -z "$DESCRIPTION" ]]; then
+    echo "Usage: $0 (ISSUE NUMBER) (DESCRIPTION)"
+    exit 1
+fi
+
+re_issue_number='^[1-9][0-9]*$'
+
+if ! [[ "$ISSUE" =~ $re_issue_number ]]; then
+    echo "Error: Issue number is not a number: $ISSUE"
+    echo
+    echo "This should preferably be the issue number that this pull request solves."
+    echo "We may also accept the Pull Request number in place of the issue."
+    exit 1
+fi
+
+echo "Issue: $ISSUE"
+echo "Description: $DESCRIPTION"
+
+FILENAME=source/upcoming_release_notes/${ISSUE}-${DESCRIPTION// /_}.rst
+
+pushd "$(dirname "$0")" || exit 1
+
+sed -e "s/IssueNumber Title/${ISSUE} ${DESCRIPTION}/" \
+    "source/upcoming_release_notes/template-short.rst" > "${FILENAME}"
+
+if ${EDITOR} "${FILENAME}"; then
+    echo "Adding ${FILENAME} to the git repository..."
+    git add "${FILENAME}"
+fi
+
+popd || exit 0

{{ cookiecutter.folder_name }}/docs/release_notes.py

@@ -0,0 +1,114 @@
+import sys
+import time
+from collections import defaultdict
+from pathlib import Path
+
+# find the pre-release directory and release notes file
+THIS_DIR = Path(__file__).resolve().parent
+PRE_RELEASE = THIS_DIR / 'source' / 'upcoming_release_notes'
+TEMPLATE = PRE_RELEASE / 'template-short.rst'
+RELEASE_NOTES = THIS_DIR / 'source' / 'releases.rst'
+
+# Set up underline constants
+TITLE_UNDER = '#'
+RELEASE_UNDER = '='
+SECTION_UNDER = '-'
+
+
+def parse_pre_release_file(path):
+    """
+    Return dict mapping of release notes section to lines.
+
+    Uses empty list when no info was entered for the section.
+    """
+    print(f'Checking {path} for release notes.')
+    with path.open('r') as fd:
+        lines = fd.readlines()
+
+    section_dict = defaultdict(list)
+    prev = None
+    section = None
+
+    for line in lines:
+        if prev is not None:
+            if line.startswith(SECTION_UNDER * 2):
+                section = prev.strip()
+                continue
+            if section is not None and line[0] in ' -':
+                notes = section_dict[section]
+                if len(line) > 6:
+                    notes.append(line)
+                section_dict[section] = notes
+        prev = line
+
+    return section_dict
+
+
+def extend_release_notes(path, version, release_notes):
+    """
+    Given dict mapping of section to lines, extend the release notes file.
+    """
+    with path.open('r') as fd:
+        lines = fd.readlines()
+
+    new_lines = ['\n', '\n']
+    date = time.strftime('%Y-%m-%d')
+    release_title = f'{version} ({date})'
+    new_lines.append(release_title + '\n')
+    new_lines.append(len(release_title) * RELEASE_UNDER + '\n')
+    new_lines.append('\n')
+    for section, section_lines in release_notes.items():
+        if section == 'Contributors':
+            section_lines = sorted(list(set(section_lines)))
+        if len(section_lines) > 0:
+            new_lines.append(section + '\n')
+            new_lines.append(SECTION_UNDER * len(section) + '\n')
+            new_lines.extend(section_lines)
+            new_lines.append('\n')
+
+    output_lines = lines[:2] + new_lines + lines[2:]
+
+    print('Writing out release notes file')
+    for line in new_lines:
+        print(line.strip('\n'))
+    with path.open('w') as fd:
+        fd.writelines(output_lines)
+
+
+def main(version_number: str):
+    section_notes = parse_pre_release_file(TEMPLATE)
+    to_delete = []
+    for path in PRE_RELEASE.iterdir():
+        if path.name[0] in '1234567890':
+            to_delete.append(path)
+            extra_notes = parse_pre_release_file(path)
+            for section, notes in section_notes.items():
+                notes.extend(extra_notes[section])
+                section_notes[section] = notes
+
+    extend_release_notes(RELEASE_NOTES, version_number, section_notes)
+
+    print(
+        "* Wrote release notes.  Please perform the following manually:",
+        file=sys.stderr,
+    )
+    for path in to_delete:
+        print(f" git rm {path}", file=sys.stderr)
+    print(f" git add {RELEASE_NOTES}", file=sys.stderr)
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 2:
+        print(f"Usage: {sys.argv[0]} VERSION_NUMBER", file=sys.stderr)
+        sys.exit(1)
+
+    version_number = sys.argv[1]
+
+    if not version_number.startswith("v"):
+        print(
+            f"Version number should start with 'v': {version_number}",
+            file=sys.stderr
+        )
+        sys.exit(1)
+
+    main(version_number)

{{ cookiecutter.folder_name }}/docs/source/index.rst

@@ -10,6 +10,8 @@ Welcome to {{ cookiecutter.project_name }}'s documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   upcoming_changes.rst
+
 .. toctree::
    :maxdepth: 1
    :caption: Links

{{ cookiecutter.folder_name }}/docs/source/upcoming_changes.rst

@@ -0,0 +1,8 @@
+Upcoming Changes
+################
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   upcoming_release_notes/[0-9]*

{{ cookiecutter.folder_name }}/docs/source/upcoming_release_notes/template-full.rst

@@ -0,0 +1,36 @@
+IssueNumber Title
+#################
+
+Update the title above with your issue number and a 1-2 word title.
+Your filename should be issuenumber-title.rst, substituting appropriately.
+
+Make sure to fill out any section that represents changes you have made,
+or replace the default bullet point with N/A.
+
+API Breaks
+----------
+- List backwards-incompatible changes here.
+  Changes to PVs don't count as API changes for this library,
+  but changing method and component names or changing default behavior does.
+
+Features
+--------
+- List new updates that add utility to many classes,
+  provide a new base classes, add options to helper methods, etc.
+
+Bugfixes
+--------
+- List bug fixes that are not covered in the above sections.
+
+Maintenance
+-----------
+- List anything else. The intent is to accumulate changes
+  that the average user does not need to worry about.
+
+Contributors
+------------
+- List your github username and anyone else who made significant
+  code or conceptual contributions to the PR. You don't need to
+  add reviewers unless their suggestions lead to large rewrites.
+  These will be used in the release notes to give credit and to
+  notify you when your code is being tagged.

{{ cookiecutter.folder_name }}/docs/source/upcoming_release_notes/template-short.rst

@@ -0,0 +1,22 @@
+IssueNumber Title
+#################
+
+API Breaks
+----------
+- N/A
+
+Features
+--------
+- N/A
+
+Bugfixes
+--------
+- N/A
+
+Maintenance
+-----------
+- N/A
+
+Contributors
+------------
+- N/A