From e5e0ef6f7b1314df231181de2b91d52fae7e57e6 Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Sat, 11 Nov 2023 15:43:59 +0100
Subject: [PATCH] complete the release note template (#637)

i've started writting the [release note for
0.86.0](https://github.com/nushell/nushell.github.io/pull/1071) and
thought we could enhance the template for the note even further:

- add some TODOs to make sure we don't forget anything
- make the `NOTE` a real note in the first section, it's just for
prettier rendering
- add some template tables in the "hall of fame"
- :exclamation: add a table of content to allow jumping back and forth
more easily when the note starts to get big
---
 make_release/release-note/template.md | 72 +++++++++++++++++++++------
 1 file changed, 58 insertions(+), 14 deletions(-)

diff --git a/make_release/release-note/template.md b/make_release/release-note/template.md
index 6ae420f..5d45c29 100644
--- a/make_release/release-note/template.md
+++ b/make_release/release-note/template.md
@@ -5,24 +5,54 @@ author_site: https://twitter.com/nu_shell
 author_image: https://www.nushell.sh/blog/images/nu_logo.png
 excerpt: Today, we're releasing version {{VERSION}} of Nu. This release adds...
 ---
+<!-- TODO: complete the excerpt above -->
 
 # Nushell {{VERSION}}
 
 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.
 
+<!-- TODO: write this excerpt -->
 Today, we're releasing version {{VERSION}} of Nu. This release adds...
 
-<!-- more -->
-
 # Where to get it
 
 Nu {{VERSION}} is available as [pre-built binaries](https://github.com/nushell/nushell/releases/tag/{{VERSION}}) or from [crates.io](https://crates.io/crates/nu). If you have Rust installed you can install it using `cargo install nu`.
 
-NOTE: The optional dataframe functionality is available by `cargo install nu --features=dataframe`.
+::: tip Note
+The optional dataframe functionality is available by `cargo install nu --features=dataframe`.
+:::
 
 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>`.
 
-# Themes of this release / New features
+# Table of content
+- [*Themes of this release / New features*](#themes-of-this-release-new-features)
+    - [*Hall of fame*](#hall-of-fame)
+        - [*Bug fixes*](#bug-fixes)
+        - [*Enhancing the documentation*](#enhancing-the-documentation)
+    - [*Our set of commands is evolving*](#our-set-of-commands-is-evolving)
+        - [*New commands*](#new-commands)
+        - [*Changes to existing commands*](#changes-to-existing-commands)
+        - [*Deprecated commands*](#deprecated-commands)
+        - [*Removed commands*](#removed-commands)
+    <!-- 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
+        ```
+    -->
+- [*Breaking changes*](#breaking-changes)
+- [*Full changelog*](#full-changelog)
+
+# Themes of this release / New features [[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)
@@ -33,16 +63,30 @@ As part of this release, we also publish a set of optional plugins you can insta
     :::
     ```
 -->
+<!-- NOTE: see https://vuepress.github.io/reference/default-theme/markdown.html#custom-containers
+    for the list of available *containers*
+-->
 
-## Hall of fame
-### Bug fixes
-### Enhancing the documentation
+## Hall of fame [[toc](#table-of-content)]
+### Bug fixes [[toc](#table-of-content)]
+Thanks to all the contributors below for helping us solve issues and bugs :pray:
+| author                               | description | url                                                     |
+| ------------------------------------ | ----------- | ------------------------------------------------------- |
+| [@author](https://github.com/author) | ...         | [#12345](https://github.com/nushell/nushell/pull/12345) |
 
-## Our set of commands is evolving
-### New commands
-### Changes to existing commands
-### Deprecated commands
-### Removed commands
+### Enhancing the documentation [[toc](#table-of-content)]
+Thanks to all the contributors below for helping us making the documentation of Nushell commands better :pray:
+| author                               | description | url                                                     |
+| ------------------------------------ | ----------- | ------------------------------------------------------- |
+| [@author](https://github.com/author) | ...         | [#12345](https://github.com/nushell/nushell/pull/12345) |
+
+## Our set of commands is evolving [[toc](#table-of-content)]
+As usual, new release rhyms with changes to commands!
+
+### New commands [[toc](#table-of-content)]
+### Changes to existing commands [[toc](#table-of-content)]
+### Deprecated commands [[toc](#table-of-content)]
+### Removed commands [[toc](#table-of-content)]
 
 <!-- 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)
@@ -62,7 +106,7 @@ As part of this release, we also publish a set of optional plugins you can insta
     ```
 -->
 
-# Breaking changes
+# Breaking changes [[toc](#table-of-content)]
 <!-- TODO:
     paste the output of
     ```nu
@@ -71,7 +115,7 @@ As part of this release, we also publish a set of optional plugins you can insta
     here
 -->
 
-# Full changelog
+# Full changelog [[toc](#table-of-content)]
 <!-- TODO:
     paste the output of
     ```nu