Merge pull request #3434 from mathesar-foundation/release_notes

docs/docs/releases/0.1.4.md

@@ -103,6 +103,10 @@ The table sidebar features a new "Cell" tab to show the content of cells, simpli
 
     _[#3271](https://github.com/mathesar-foundation/mathesar/pull/3271) [#3146](https://github.com/mathesar-foundation/mathesar/pull/3146)_
 
+## Documentation
+
+- We improved and updated our documentation for installing and updating Mathesar. _([#3227](https://github.com/mathesar-foundation/mathesar/pull/3227))_
+
 ## Bug fixes
 
 - Tables having `CHECK` constraints are now usable within Mathesar. _([#3243](https://github.com/mathesar-foundation/mathesar/pull/3243))_
@@ -134,5 +138,6 @@ The table sidebar features a new "Cell" tab to show the content of cells, simpli
 - We improved testing against DB objects with long names _([#3140](https://github.com/mathesar-foundation/mathesar/pull/3140))_
 - We updated our org name to reflect a change from "Center of Complex Interventions" to "Mathesar Foundation". _([#3312](https://github.com/mathesar-foundation/mathesar/pull/3312))_
 - We made some improvements to our developer documentation. _([#3300](https://github.com/mathesar-foundation/mathesar/pull/3300) [#3210](https://github.com/mathesar-foundation/mathesar/pull/3210) [#3279](https://github.com/mathesar-foundation/mathesar/pull/3279))_
+- We improved our process for generating release notes. _([#3427](https://github.com/mathesar-foundation/mathesar/pull/3427))_
 - We resolved some merge conflicts after finalizing our previous release. _([#3190](https://github.com/mathesar-foundation/mathesar/pull/3190))_
 

docs/docs/releases/README.md

@@ -4,23 +4,35 @@ This is developer documentation to help with release notes. It is not published
 
 ## How to generate release notes
 
-1. Create an empty release notes file.
-
-    For example:
-
-    ```
-    touch 1.2.3.md
-    ```
-
-1. Run this script to find PRs which have been merged but not yet included in the latest release notes file.
+1. Run the `find_missing_prs.sh` script, passing the release version number as the only argument.
 
     ```
-    ./find_missing_prs.sh
+    ./find_missing_prs.sh 1.2.3
     ```
 
-    (See comments within the script to better understand how it works.)
+    - You can run this any time during the development cycle. If there is not yet a release branch, the script will compare `develop` to the previous release.
+    - If you haven't yet created a release notes file for this release, it will create one for you.
+    - The script will find PRs which have been merged but not yet included in the release notes file.
 
 1. Open `missing_prs.csv` to see the PRs you need to add. Incorporate them into the release notes as you see fit. Save the release notes and commit them.
 
 1. Re-run the script as needed. When more PRs are merged, they will appear in `missing_prs.csv`.
 
+## How to format the release notes content
+
+1. Group changes into sections in the following order
+
+    ```md
+    ## Security fixes
+    ## Breaking changes
+    ## New features
+    ## Groundwork
+    ## Documentation
+    ## Bug fixes
+    ## Maintenance
+    ```
+
+    You can omit sections if there are no applicable changes.
+
+1. Within the "New features" section, further categorize changes by specific features using level 3 headings.
+

docs/docs/releases/find_missing_prs.sh

@@ -1,11 +1,52 @@
 #!/usr/bin/env bash
 
-## DEPENDENCIES
-##
-## This script requires the following things to be installed:
-##
-## - The GitHub CLI: https://cli.github.com/
-## - DuckDB: https://duckdb.org/
+function print_help {
+    cat << EOF
+Usage: $(basename $0) <VERSION_NUMBER>
+
+Description:
+    This script finds all the PRs that have been merged into the release branch
+    but have not yet been included in the release notes.
+
+Arguments:
+    VERSION_NUMBER: (Required) e.g. "0.1.0"
+
+Options:
+    --help: Print this help message.
+EOF
+}
+
+if [[ $# -eq 0 || "$1" == "--help" ]]; then
+    print_help
+    exit 0
+fi
+
+if ! type duckdb >/dev/null 2>&1; then
+  echo "Error: This script requires DuckDB to be installed." \
+    "The 'duckdb' command must be in your path." \
+    "See installation instructions at:"
+  echo "  https://duckdb.org/"
+  exit 1
+fi
+
+if ! type gh >/dev/null 2>&1; then
+  echo "Error: This script requires the GitHub CLI to be installed." \
+    "The 'gh' command must be in your path." \
+    "See installation instructions at:"
+  echo "  https://cli.github.com/"
+  exit 1
+fi
+
+RELEASE=$1
+NOTES_FILE=$RELEASE.md
+
+# If the notes file doesn't yet exist, create one
+if [ ! -f $NOTES_FILE ]; then
+  echo "# Mathesar $RELEASE" > $NOTES_FILE
+fi
+
+PREV_NOTES_FILE=$(ls -1 | sort | grep -B 1 $NOTES_FILE | head -n 1)
+PREV_RELEASE=$(echo $PREV_NOTES_FILE | sed s/.md$//)
 
 COMMITS_FILE=cache/commits.txt
 ALL_PRS_FILE=cache/all_prs.json
@@ -33,7 +74,7 @@ RELEASE_BRANCH=$(
 
 # Find and cache the hashes for all the PR-merge commits included in the release
 # branch but not included in the master branch.
-git log --format=%H --first-parent master..$RELEASE_BRANCH > $COMMITS_FILE
+git log --format=%H --first-parent $PREV_RELEASE..$RELEASE_BRANCH > $COMMITS_FILE
 
 # Find and cache details about all the PRs merged within the past year. This
 # gets more PRs than we need, but we'll filter it shortly.
@@ -75,3 +116,7 @@ echo "
   ORDER BY pr.additions DESC;" | \
   duckdb -csv > $MISSING_PRS_FILE
 
+COUNT=$(tail -n +2 $MISSING_PRS_FILE | wc -l)
+
+echo "$COUNT missing PRs written to $MISSING_PRS_FILE"
+