Edit release notes template and edit scripts

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
-
-- [ ] 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*
+## 4. Publish the release notes on the website
+
+- [ ] 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)

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
+}

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
-    ```
--->
 
-# Highlights and themes of this release [[toc](#table-of-content)]
+<!-- 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
+
 <!-- 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`.
 -->