From fc1d1989b64ad4d32b3b07e6719874365861b972 Mon Sep 17 00:00:00 2001
From: Ian Manske <ian.manske@pm.me>
Date: Thu, 21 Nov 2024 19:12:26 -0800
Subject: [PATCH] Edit release notes template and edit scripts (#981)

Making the release scripts easier to use as well as automating more of
the process.
---
 make_release/Readme.md                        |  14 +--
 .../release-note/{create-pr => create-pr.nu}  |   0
 make_release/release-note/get-full-changelog  |  27 -----
 ...-release-excerpt => gh-release-excerpt.nu} |   0
 make_release/release-note/list-merged-prs     | 100 ----------------
 make_release/release-note/notes.nu            | 108 ++++++++++++++++++
 make_release/release-note/template.md         |  96 +++++-----------
 7 files changed, 138 insertions(+), 207 deletions(-)
 rename make_release/release-note/{create-pr => create-pr.nu} (100%)
 delete mode 100755 make_release/release-note/get-full-changelog
 rename make_release/release-note/{gh-release-excerpt => gh-release-excerpt.nu} (100%)
 delete mode 100755 make_release/release-note/list-merged-prs
 create mode 100755 make_release/release-note/notes.nu

diff --git a/make_release/Readme.md b/make_release/Readme.md
index c43c269..f2d5161 100644
--- a/make_release/Readme.md
+++ b/make_release/Readme.md
@@ -71,19 +71,13 @@
 > - edit the `nu_release.nu` script to start again where it failed
 > - re-run the script
 
-## 4. Publish the release note on the website
-> **Note**
-> the scripts have been written in such a way they can be run from anywhere
+## 4. Publish the release notes on the website
 
-- [ ] inspect the merged PRs to write changelogs with `./make_release/release-note/list-merged-prs nushell/nushell`
-- [ ] reorder sections by priority, what makes the most sense to the user?
-- [ ] paste the output of `./make_release/release-note/list-merged-prs nushell/nushell --label pr:breaking-change --pretty --no-author` to the "*Breaking changes*" section
-- [ ] make sure breaking changes titles are clear enough
-- [ ] paste the output of `./make_release/release-note/get-full-changelog` to the "*Full changelog*" section
-- [ ] mark as *ready for review* when uploading to *crates.io*
+- [ ] follow and finish the TODOs in the release notes file
+- [ ] mark as ready for review when uploading to crates.io
 - [ ] land when
     - **fully uploaded** to *crates.io*
-    - **before** the *GitHub* release
+    - **before** the GitHub release
 
 ## 5. Publish the release on *GitHub*
 - [ ] go to the draft release on the [release page](https://github.com/nushell/nushell/releases)
diff --git a/make_release/release-note/create-pr b/make_release/release-note/create-pr.nu
similarity index 100%
rename from make_release/release-note/create-pr
rename to make_release/release-note/create-pr.nu
diff --git a/make_release/release-note/get-full-changelog b/make_release/release-note/get-full-changelog
deleted file mode 100755
index 5692317..0000000
--- a/make_release/release-note/get-full-changelog
+++ /dev/null
@@ -1,27 +0,0 @@
-#!/usr/bin/env nu
-
-def main [
-    date?: datetime  # the date of the last release (default to 4 weeks ago, excluded)
-] {
-    let list_merged_prs_script = (
-        $env.CURRENT_FILE | path dirname | path join "list-merged-prs"
-    )
-
-    let changelogs = [
-        [title repo];
-
-        [Nushell nushell/nushell]
-        [Extension nushell/vscode-nushell-lang]
-        [Documentation nushell/nushell.github.io]
-        [Nu_Scripts nushell/nu_scripts]
-        [Reedline nushell/reedline]
-    ]
-
-    $changelogs | each {|changelog|
-        [
-            $"## ($changelog.title)"
-            (^$list_merged_prs_script $changelog.repo --pretty $date)
-        ] | str join "\n"
-    }
-    | str join "\n\n"
-}
diff --git a/make_release/release-note/gh-release-excerpt b/make_release/release-note/gh-release-excerpt.nu
similarity index 100%
rename from make_release/release-note/gh-release-excerpt
rename to make_release/release-note/gh-release-excerpt.nu
diff --git a/make_release/release-note/list-merged-prs b/make_release/release-note/list-merged-prs
deleted file mode 100755
index b164696..0000000
--- a/make_release/release-note/list-merged-prs
+++ /dev/null
@@ -1,100 +0,0 @@
-#!/usr/bin/env nu
-use std log
-
-def md-link [
-    text: string
-    link: string
-] {
-    $"[($text)]\(($link)\)"
-}
-
-# list all merged PRs since last release
-export def main [
-    repo: string  # the name of the repo, e.g. `nushell/nushell`
-    --date: datetime  # the date of the last release (default to 4 weeks ago, excluded, if no milestone is set)
-    --milestone: string # search PRs by milestone
-    --label: string  # the label to filter the PRs by, e.g. `good-first-issue`
-    --pretty # pretty-print for the MarkDown release not
-    --no-author # do not group the contributions by author
-    --table # make an Antoine table
-] {
-    mut query_parts = []
-
-    let date = if $date == null and $milestone == null {
-        (date now) - 4wk
-    } else {
-        $date
-    }
-
-    if $date != null {
-        let date = $date | format date "%Y-%m-%d"
-        let since = (date now | format date %F | into datetime) - ($date | into datetime)
-        log info $"listing PRs in ($repo) since ($date) \(($since) ago\)"
-        $query_parts ++= [ $"merged:>($date)" ]
-    }
-
-    if $milestone != null {
-        log info $"listing PRs in milestone ($milestone)"
-        $query_parts ++= [ $'milestone:"($milestone)"' ]
-    }
-
-    if $label != null {
-        log info $"listing PRs with label ($label)"
-        $query_parts ++= [ $'label:($label)' ]
-    }
-
-    let query = $query_parts | str join ' '
-
-    let prs = (
-        gh --repo $repo pr list
-            --state merged
-            --limit (inf | into int)
-            --json author,title,number,mergedAt,url
-            --search $query
-        | from json
-        | sort-by mergedAt --reverse
-        | update author { get login }
-    )
-
-    if $table {
-        return (
-            $prs
-            | update author {md-link $"@($in)" $"https://github.com/($in)"}
-            | insert PR {|pr| md-link $"#($pr.number)" $pr.url}
-            | select author title PR
-            | to md
-        )
-    }
-
-    if $pretty {
-        if $no_author {
-            return (
-                $prs | each {|pr|
-                    let link = (md-link $"#($pr.number)" $pr.url)
-                    $"- ($link) ($pr.title)"
-                }
-                | str join "\n"
-            )
-        }
-
-        return (
-            $prs
-            | group-by author
-            | transpose author prs
-            | each {|line|
-                let author = (md-link $line.author $"https://github.com/($line.author)")
-
-                $"- ($author) created" | append (
-                    $line.prs | each {|pr|
-                        let link = (md-link $pr.title $pr.url)
-                        $"    - ($link)"
-                    }
-                )
-                | str join "\n"
-            }
-            | to text
-        )
-    }
-
-    $prs
-}
diff --git a/make_release/release-note/notes.nu b/make_release/release-note/notes.nu
new file mode 100755
index 0000000..74c7e34
--- /dev/null
+++ b/make_release/release-note/notes.nu
@@ -0,0 +1,108 @@
+def md-link [text: string, link: string] {
+    $"[($text)]\(($link)\)"
+}
+
+# List all merged PRs since the last release
+export def list-prs [
+    repo: string = 'nushell/nushell' # the name of the repo, e.g. 'nushell/nushell'
+    --since: datetime # list PRs on or after this date (defaults to 4 weeks ago if `--milestone` is not provided)
+    --milestone: string # only list PRs in a certain milestone
+    --label: string # the PR label to filter by, e.g. 'good-first-issue'
+] {
+    mut query_parts = []
+
+    if $since != null or $milestone == null {
+        let date = $since | default ((date now) - 4wk) | format date '%Y-%m-%d'
+        $query_parts ++= [ $'merged:>($date)' ]
+    }
+
+    if $milestone != null {
+        $query_parts ++= [ $'milestone:"($milestone)"' ]
+    }
+
+    if $label != null {
+        $query_parts ++= [ $'label:($label)' ]
+    }
+
+    let query = $query_parts | str join ' '
+
+    (gh --repo $repo pr list --state merged
+        --limit (inf | into int)
+        --json author,title,number,mergedAt,url
+        --search $query)
+    | from json
+    | sort-by mergedAt --reverse
+    | update author { get login }
+}
+
+# Format the output of `list-prs` as a markdown table
+export def pr-table [] {
+    sort-by author number
+    | update author { md-link $'@($in)' $'https://github.com/($in)' }
+    | insert link {|pr| md-link $'#($pr.number)' $pr.url }
+    | select author title link
+    | to md
+}
+
+const toc = '[[toc](#table-of-content)]'
+
+# Generate and write the table of contents to a release notes file
+export def write-toc [file: path] {
+    let lines = open $file | lines | each { str trim -r }
+
+    let content_start = 2 + (
+        $lines
+        | enumerate
+        | where item == '# Table of contents'
+        | first
+        | get index
+    )
+
+    let data = (
+        $lines
+        | range $content_start..
+        | wrap line
+        | insert level {
+            get line | split chars | take while { $in == '#' } | length
+        }
+    )
+
+    let table_of_contents = (
+        $data
+        | where level in 1..=3
+        | each {|header|
+            let indent = '- ' | fill -w ($header.level * 2) -a right
+
+            let text = $header.line | str trim -l -c '#' | str trim -l
+            let text = if $text ends-with $toc {
+                $text | str substring ..<(-1 * ($toc | str length)) | str trim -r
+            } else {
+                $text
+            }
+
+            let link = (
+                $text
+                | str replace -a '`' ''
+                | str replace -a ' ' '-'
+                | str replace -a -r '--+' '-'
+            )
+
+            $"($indent)[_($text)_]\(#($link)-toc\)"
+        }
+    )
+
+    let content = $data | each {
+        if $in.level in 1..=3 and not ($in.line ends-with $toc) {
+            $'($in.line) ($toc)'
+        } else {
+            $in.line
+        }
+    }
+
+    [
+        ...($lines | range ..<$content_start)
+        ...$table_of_contents
+        ...$content
+    ]
+    | save -r -f $file
+}
diff --git a/make_release/release-note/template.md b/make_release/release-note/template.md
index a0e7a51..77d977c 100644
--- a/make_release/release-note/template.md
+++ b/make_release/release-note/template.md
@@ -7,9 +7,9 @@ excerpt: Today, we're releasing version {{VERSION}} of Nu. This release adds...
 ---
 <!-- TODO: complete the excerpt above -->
 
-# Nushell {{VERSION}}
+<!-- NOTE: start from the TODO all the way at the bottom (and sort of work your way up) -->
 
-Nushell, or Nu for short, is a new shell that takes a modern, structured approach to your command line. It works seamlessly with the data from your filesystem, operating system, and a growing number of file formats to make it easy to build powerful command line pipelines.
+# Nushell {{VERSION}}
 
 <!-- TODO: write this excerpt -->
 Today, we're releasing version {{VERSION}} of Nu. This release adds...
@@ -21,33 +21,11 @@ Nu {{VERSION}} is available as [pre-built binaries](https://github.com/nushell/n
 As part of this release, we also publish a set of optional plugins you can install and use with Nu. To install, use `cargo install nu_plugin_<plugin name>`.
 
 # Table of contents
-- [_Highlights and themes of this release_](#highlights-and-themes-of-this-release-toc)
-- [_Changes_](#changes-toc)
-  - [_Additions_](#additions-toc)
-  - [_Breaking changes_](#breaking-changes-toc)
-  - [_Deprecations_](#deprecations-toc)
-  - [_Removals_](#removals-toc)
-  - [_Bug fixes and other changes_](#bug-fixes-and-other-changes-toc)
-- [_Notes for plugin developers_](#notes-for-plugin-developers-toc)
-- [_Hall of fame_](#hall-of-fame-toc)
-- [_Full changelog_](#full-changelog-toc)
-<!-- TODO: please add links to the other sections here
 
-    the following command should help pre-generate a great deal of the table of content.
-    be careful with the format and false-positives :wink:
-    ```nushell
-    rg '^#+ ' blog/...
-        | lines
-        | each {
-            str replace '# ' '- '
-                | str replace --all '#' '    '
-                | str replace --regex '- (.*)' '- [_$1_](#$1-toc)'
-        }
-        | to text
-    ```
--->
+<!-- TODO: once all the content below is finished and committed, `use nu_scripts/make_release/release-note/notes.nu *` and run `write-toc $this_file`. -->
+
+# Highlights and themes of this release
 
-# Highlights and themes of this release [[toc](#table-of-content)]
 <!-- NOTE: if you wanna write a section about a breaking change, when it's a very important one,
     please add the following snippet to have a "warning" banner :)
     > see [an example](https://www.nushell.sh/blog/2023-09-19-nushell_0_85_0.html#pythonesque-operators-removal)
@@ -62,60 +40,38 @@ As part of this release, we also publish a set of optional plugins you can insta
     for the list of available *containers*
 -->
 
-# Changes [[toc](#table-of-content)]
+# Changes
 
-## Additions [[toc](#table-of-content)]
+## Additions
 
-## Breaking changes [[toc](#table-of-content)]
+## Breaking changes
 
-## Deprecations [[toc](#table-of-content)]
+## Deprecations
 
-## Removals [[toc](#table-of-content)]
+## Removals
 
-## Bug fixes and other changes [[toc](#table-of-content)]
+## Bug fixes and other changes
 
-<!-- NOTE: to start investigating the contributions of last release, i like to list them all in a raw table.
-    to achieve this, one can use the [`list-merged-prs` script from `nu_scripts`](https://github.com/nushell/nu_scripts/blob/main/make_release/release-note/list-merged-prs)
-    as follows:
+# Notes for plugin developers
 
-    ```nushell
-    use ./make_release/release-note/list-merged-prs
-    use std clip
+# Hall of fame
 
-    let last_release_date = ^gh api /repos/nushell/nushell/releases
-        | from json
-        | into datetime published_at
-        | get published_at
-        | sort
-        | last
+Thanks to all the contributors below for helping us solve issues, improve documentation, refactor code, and more! :pray:
 
-    let prs = list-merged-prs nushell/nushell $last_release_date
-        | sort-by mergedAt
-        | update url {|it| $"[#($it.number)]\(($it.url)\)" }
-        | update author { $"[@($in)]\(https://github.com/($in)\)" }
-        | select author title url
-        | rename -c {url: pr}
-        | to md --pretty
-
-    $prs | to md --pretty | clip
-    ```
--->
-
-# Notes for plugin developers [[toc](#table-of-content)]
-
-# Hall of fame [[toc](#table-of-content)]
-
-Thanks to all the contributors below for helping us solve issues and improve documentation :pray:
-
-| author                               | title       | url                                                     |
+| author                               | title       | link                                                    |
 | ------------------------------------ | ----------- | ------------------------------------------------------- |
 | [@author](https://github.com/author) | ...         | [#12345](https://github.com/nushell/nushell/pull/12345) |
 
-# Full changelog [[toc](#table-of-content)]
+# Full changelog
+
 <!-- TODO:
-    paste the output of
-    ```nu
-    ./make_release/release-note/get-full-changelog
-    ```
-    here
+    - `use nu_scripts/make_release/release-note/notes.nu *`
+    - run `list-prs --milestone v{{VERSION}} | pr-table`
+    - paste the output here
+
+Afterwards, go through each PR and clasify it as one of the following:
+    - A user-facing change. These PRs should go into the `# Changes` section.
+    - A plugin-facing change. These PRs should go in `# Notes for plugin developers`. Some plugin-facing changes might also be a user-facing change and vice versa.
+    - A documentation improvement, error message improvement, refactoring PR, clippy fix, typo fix, etc. These PRs go into the `# Hall of fame`. You can just copy the table row in this section and paste it to the `# Hall of fame` section above. Note that major refactorings may warrant a section in `# Highlights`.
+    - Dependabot PRs and version bumps should be ignored. They will only be mentioned in `# Full changelog`.
 -->