Merge pull request #1907 from rsteube/doc-more-changelog

doc: more changelogs

docs/src/changelog/v0.13.md

@@ -1 +1,7 @@
-# v0.13
+# v0.13 - Furious
+
+![](./v0.13/banner.png)
+
+## fury.io
+
+`DEB` and `RPM` packages are now published to [fury.io](https://rsteube.fury.site/) ([Installation](https://rsteube.github.io/carapace-bin/installation.html))

docs/src/changelog/v0.14.md

@@ -1 +1,25 @@
-# v0.14
+# v0.14 - In A Nutshell
+
+![](./v0.14/banner.png)
+
+
+## Nushell
+
+https://github.com/nushell/nushell/pull/6295 adds support for external completers to nushell.
+For this `config.nu` must be updated manually according to the snippet output of `carapace`.
+Here's an example with `carapace` as default completer and a couple custom completers:
+
+```sh
+let external_completer = {|spans| 
+  {
+    $spans.0: { carapace $spans.0 nushell $spans | from json } # default                                                             
+    example: { example _carapace nushell $spans | from json }                                                                 
+    pkill: { carapace --spec '/home/rsteube/.config/carapace/specs/pkill.yaml' nushell $spans | from json }  
+    vault: { carapace --bridge vault/posener nushell $spans | from json }
+  } | get $spans.0 | each {|it| do $it}
+}
+
+let-env config = {
+  external_completer: $external_completer
+}
+```

docs/src/changelog/v0.15.md

@@ -1 +1,12 @@
-# v0.15
+# v0.15 - Porcelain Shop
+
+![](./v0.15/banner.png)
+
+## ZSH (this might break some stuff)
+
+Added support for homedir (`~`) and [static named directories](https://zsh.sourceforge.io/Doc/Release/Expansion.html#Static-named-directories).
+These are not expanded by zsh for the completion function are thus now handled by carapace.
+Quoting of special characters is now also done in carapace instead of [compadd](https://zsh.sourceforge.io/Doc/Release/Completion-Widgets.html#Completion-Builtin-Commands) to skip `~` at appropriate times.
+Edge cases where this doesn't work and some initial bugs regarding special characters not yet being handled correctly are expected.
+
+see [#1277](https://github.com/rsteube/carapace-bin/issues/1277)

docs/src/changelog/v0.16.md

@@ -1 +1,19 @@
-# v0.16
+# v0.16 - Pandoras Box
+
+![](./v0.16/banner.png)
+
+Switched to a [custom pflag fork](https://github.com/rsteube/carapace-pflag) with adaptions for non-posix variants like long shorthands (e.g. `-shorthand`).
+
+> So far this has been done by patching `os.Args` which was rather hacky.
+Modifications to the flag parser are quite complex though, so there might be some issues.
+
+see [#1293](https://github.com/rsteube/carapace-bin/pull/1293/files)
+
+[Spec](https://github.com/rsteube/carapace-spec) files support non-posix flags now as well:
+
+```yaml
+flags:
+  -np: non-posix shorthand
+  -np, -nonposix:  non-posix shorthand and longhand
+  -np, --nonposix: non-posix shorthand mixed with posix longhand
+```

docs/src/changelog/v0.18.md

@@ -1 +1,31 @@
-# v0.18
+# v0.18 - Spec Galore
+
+![](./v0.18/banner.png)
+
+## Generate
+
+Specs can now be generated from [clap](https://github.com/clap-rs/clap) based commands with [carapace-spec-clap](https://github.com/rsteube/carapace-spec-clap).
+
+![](./v0.18/generate.png)
+
+## Scrape
+
+For advanced completion these can further be converted to Go code with `carapace --scrape [spec]`.
+
+![](./v0.18/scrape.png)
+
+## Json Schema
+
+A [JSON Schema](https://json-schema.org/) is now written to [`${UserConfigDir}/carapace/schema.json`](https://pkg.go.dev/os#UserConfigDir).
+
+![](./v0.18/schema.png)
+
+It can be used by adding the following header to a user spec:
+
+```yaml
+# yaml-language-server: $schema=../schema.json
+```
+
+## Windows
+
+`$(shell command)` is now executed in Powershell on windows.

docs/src/changelog/v0.19.md

@@ -1 +1,53 @@
-# v0.19
+# v0.19 - Group Therapy
+
+![](./v0.19/banner.png)
+
+## Error messages
+
+Multiple error message are now supported.
+In `elvish` and `zsh` these are shown separate from the completion values.
+
+![](./v0.19/error-message.png)
+
+## Usage message
+
+Added Usage message which defaults to flag description / command usage.
+This is only supported in `elvish` and `zsh`.
+Since notifications are persistent in `elvish` it is only shown when there are no values to complete.
+
+![](./v0.19/usage-message.png)
+
+## Tags
+
+Completion values can now be tagged. Based on this they are grouped in `zsh`.
+
+![](./v0.19/tags.png)
+
+## Command groups
+
+Subcommands can now be grouped and will be highlighted in different colors.
+
+![](./v0.19/command-groups.png)
+
+## Group names
+
+Group names can be shown in `zsh` with the following `zstyle`.
+
+```zsh
+zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m'
+```
+
+## Group ordering
+
+Order of the groups can be configured in `zsh` with the following `zstyle`.
+
+```zsh
+zstyle ':completion:*:git:*' group-order 'main commands' 'alias commands' 'external commands'
+```
+
+## _describe
+
+`_describe` is now used in `zsh` which enables the grouping of tags.
+With this aliased commands and flags are now also arranged side by side.
+
+![](./v0.19/describe.png)

docs/src/changelog/v0.20.md

@@ -1 +1,15 @@
-# v0.20
+# v0.20 - Blinkers
+
+![](./v0.20/banner.png)
+
+### Export
+
+Contains breaking changes on the [export](https://rsteube.github.io/carapace/carapace/export.html) format.
+Since there is no backward compability any embedded external carapace based completion must be `>= v0.31.0`.
+
+
+### Lenient
+
+When environment variable `CARAPACE_LENIENT` is set (e.g. `export CARAPACE_LENIENT=1`) unknown flags are ignored.
+Completers are supposed to be aware of all existing flags but can out of date or not yet working correctly.
+This can be used to suppress the errors until issues are fixed.

docs/src/changelog/v0.21.md

@@ -1 +1,39 @@
-# v0.21
+# v0.21 - Heart Transplant
+
+![](./v0.21/banner.png)
+
+Replaced command traversal with a full rewrite.
+This provides more fine-grained control and improved logging.
+It is a complex core component though and while tests are looking good so far some edge cases are likely to fail.
+
+
+## Logging
+
+Improved logging output (`export CARAPACE_LOG=1`):
+
+```go
+// /tmp/carapace/carapace.log
+2023/01/29 11:46:28.310133 elvish []string{"/home/rsteube/go/bin/carapace", "_carapace", "elvish", "git", "-C", "../carapace-bin/", "log", "--author", ""}
+2023/01/29 11:46:28.310165 elvish traverse called for "git" with args []string{"-C", "../carapace-bin/", "log", "--author", ""}
+2023/01/29 11:46:28.310167 elvish executing PreRun for "git" with args []string{"-C", "../carapace-bin/", "log", "--author", ""}
+2023/01/29 11:46:28.310185 elvish arg "-C" is a flag
+2023/01/29 11:46:28.310207 elvish arg "../carapace-bin/" is a flag argument
+2023/01/29 11:46:28.310210 elvish arg "log" is a subcommand
+2023/01/29 11:46:28.310211 elvish parsing flags for "git" with args []string{"-C", "../carapace-bin/"}
+2023/01/29 11:46:28.310215 elvish traverse called for "log" with args []string{"--author", ""}
+2023/01/29 11:46:28.310247 elvish arg "--author" is a flag
+2023/01/29 11:46:28.310259 elvish removing arg "--author" since it is a flag missing its argument
+2023/01/29 11:46:28.310260 elvish parsing flags for "log" with args []string{}
+2023/01/29 11:46:28.310262 elvish completing flag argument of "author" for arg ""
+```
+
+## Yargs
+
+Added bridge for [yargs](https://github.com/yargs/yargs):
+
+```yaml
+name: ng
+description: CLI tool for Angular
+completion:
+  positionalany: ["$_bridge.Yargs(ng)"]
+```

docs/src/changelog/v0.22.md

@@ -1 +1,72 @@
-# v0.22
+# v0.22 - Running Man
+
+![](./v0.22/banner.png)
+
+Specs now support a `run` field enabling cross shell aliases and simple nested custom commands.
+
+## Run
+
+`run` can either contain an alias (`[command, arg1, arg2]`) which bridges completion or a shell macro (`$(echo example)`) with custom completions / flag parsing.
+
+```yaml
+name: runnable
+description: runnable spec
+commands:
+  -  name: sub1
+     description: alias
+     run: "[git, log]"
+
+  -  name: sub2
+     description: shell
+     run: "$(git show $1)"
+     completion:
+       positional:
+         - - "$(git branch --format '%(refname:short)\t%(subject)\tblue')"
+           - "$(git tag --format '%(refname:short)\t\tyellow')"
+
+  -  name: sub3
+     description: shell with flags
+     run: "$(git log --author \"${C_FLAG_AUTHOR}\" $1)"
+     flags:
+       -a, --author=: limit to author
+     completion:
+       flag:
+         author: ["$(git shortlog --summary --email HEAD | sed -e 's/^.*\t//' -e 's/ </\t</')"]
+       positional:
+         - - "$(git branch --format '%(refname:short)\t%(subject)\tblue')"
+           - "$(git tag --format '%(refname:short)\t\tyellow')"
+```
+
+![](./v0.22/runnable.cast)
+
+## PATH
+
+`carapace _carapace` now prepends [`${UserConfigDir}/carapace/bin`] to `PATH` unless it already exists.
+
+> In `nushell` this needs to be done manually (see output of `carapace _carapace nushell`):
+> ```nushell
+> let-env PATH = ($env.PATH | prepend "/home/rsteube/.config/carapace/bin")
+> ```
+
+## Shim
+
+It also creates [Shims](https://en.wikipedia.org/wiki/Shim_(computing)) in [`${UserConfigDir}/carapace/bin`] to execute the specs.
+For unix systems this is a simple shell script, but for windows an [embedded binary](https://github.com/rsteube/carapace-bin/blob/v0.22.0/cmd/shim/main.go) is used.
+
+```sh
+#!/bin/sh
+carapace --run "/home/rsteube/.config/carapace/specs/runnable.yaml" "$@"
+```
+
+> The [`${UserConfigDir}/carapace/bin`] directory is fully managed by carapace and **unrelated files within it are removed**.
+
+## Nargs
+
+Initial support for flags consuming multiple arguments as seen in [argparse](https://docs.python.org/3/library/argparse.html#nargs) and various `nix` commands.
+
+## XDG
+
+[XDG] base directories for `XDG_CACHE_HOME` and `XDG_CONFIG_HOME` are now supported.
+
+[`${UserConfigDir}/carapace/bin`]:https://pkg.go.dev/os#UserConfigDir
+[XDG]:https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html