From 8afeaf05c4063d48e65d2d82c31c3323c3237f7c Mon Sep 17 00:00:00 2001
From: Peter Kolloch <info@eigenvalue.net>
Date: Tue, 28 Nov 2023 19:02:15 +0100
Subject: [PATCH] Add docs/rl-notes for `nix hash convert` /
 `builtins.convertHash`

https://github.com/NixOS/nix/issues/8876
---
 doc/manual/rl-next/hash-format-nix32.md | 22 ++++++++++++
 doc/manual/rl-next/nix-hash-convert.md  | 47 +++++++++++++++++++++++++
 src/libexpr/primops.cc                  |  8 ++---
 src/nix/hash.cc                         |  2 +-
 4 files changed, 74 insertions(+), 5 deletions(-)
 create mode 100644 doc/manual/rl-next/hash-format-nix32.md
 create mode 100644 doc/manual/rl-next/nix-hash-convert.md

diff --git a/doc/manual/rl-next/hash-format-nix32.md b/doc/manual/rl-next/hash-format-nix32.md
new file mode 100644
index 000000000..20c557da9
--- /dev/null
+++ b/doc/manual/rl-next/hash-format-nix32.md
@@ -0,0 +1,22 @@
+synopsis: Rename hash format `base32` to `nix32`
+prs: #9452
+description: {
+
+Hash format `base32` was renamed to `nix32` since it used a special nix-specific character set for 
+[Base32](https://en.wikipedia.org/wiki/Base32).
+
+## Deprecation: Use `nix32` instead of `base32` as `toHashFormat`
+
+For the builtin `convertHash`, the `toHashFormat` parameter now accepts the same hash formats as the `--to`/`--from`
+parameters of the `nix hash conert` command: `"base16"`, `"nix32"`, `"base64"`, and `"sri"`. The former `"base32"` value
+remains as a deprecated alias for `"base32"`. Please convert your code from:
+
+```nix
+builtins.convertHash { inherit hash hashAlgo; toHashFormat = "base32";}
+```
+
+to
+
+```nix
+builtins.convertHash { inherit hash hashAlgo; toHashFormat = "nix32";}
+```
\ No newline at end of file
diff --git a/doc/manual/rl-next/nix-hash-convert.md b/doc/manual/rl-next/nix-hash-convert.md
new file mode 100644
index 000000000..de4367c5b
--- /dev/null
+++ b/doc/manual/rl-next/nix-hash-convert.md
@@ -0,0 +1,47 @@
+synopsis: Add `nix hash convert`
+prs: #9452
+description: {
+
+New [`nix hash convert`](https://github.com/NixOS/nix/issues/8876) sub command with a fast track
+to stabilization! Examples:
+
+- Convert the hash to `nix32`.
+
+  ```bash
+  $ nix hash convert --algo "sha1" --to nix32 "800d59cfcd3c05e900cb4e214be48f6b886a08df"
+  vw46m23bizj4n8afrc0fj19wrp7mj3c0
+  ```
+  `nix32` is a base32 encoding with a nix-specific character set.
+  Explicitly specify the hashing algorithm (optional with SRI hashes) but detect hash format by the length of the input
+  hash.
+- Convert the hash to the `sri` format that includes an algorithm specification:
+  ```bash
+  nix hash convert --algo "sha1" "800d59cfcd3c05e900cb4e214be48f6b886a08df"
+  sha1-gA1Zz808BekAy04hS+SPa4hqCN8=
+  ```
+  or with an explicit `-to` format:
+  ```bash
+  nix hash convert --algo "sha1" --to sri "800d59cfcd3c05e900cb4e214be48f6b886a08df"
+  sha1-gA1Zz808BekAy04hS+SPa4hqCN8=
+  ```
+- Assert the input format of the hash:
+  ```bash
+  nix hash convert --algo "sha256" --from nix32 "ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0="
+  error: input hash 'ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=' does not have the expected format '--from nix32'
+  nix hash convert --algo "sha256" --from nix32 "1b8m03r63zqhnjf7l5wnldhh7c134ap5vpj0850ymkq1iyzicy5s"
+  sha256-ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
+  ```
+
+The `--to`/`--from`/`--algo` parameters have context-sensitive auto-completion.
+
+## Related Deprecations
+
+The following commands are still available but will emit a deprecation warning. Please convert your code to
+`nix hash convert`:
+
+- `nix hash to-base16 $hash1 $hash2`: Use `nix hash convert --to base16 $hash1 $hash2` instead.
+- `nix hash to-base32 $hash1 $hash2`: Use `nix hash convert --to nix32 $hash1 $hash2` instead.
+- `nix hash to-base64 $hash1 $hash2`: Use `nix hash convert --to base64 $hash1 $hash2` instead.
+- `nix hash to-sri $hash1 $hash2`: : Use `nix hash convert --to sri $hash1 $hash2`
+  or even just `nix hash convert $hash1 $hash2` instead.
+}
diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
index 7831f3803..4162a8da3 100644
--- a/src/libexpr/primops.cc
+++ b/src/libexpr/primops.cc
@@ -1339,7 +1339,7 @@ drvName, Bindings * attrs, Value & v)
                 .errPos = state.positions[noPos]
             });
 
-        auto ht = parseHashAlgoOpt(outputHashAlgo).value_or(HashAlgorithm::SHA256);
+        auto ha = parseHashAlgoOpt(outputHashAlgo).value_or(HashAlgorithm::SHA256);
         auto method = ingestionMethod.value_or(FileIngestionMethod::Recursive);
 
         for (auto & i : outputs) {
@@ -1348,13 +1348,13 @@ drvName, Bindings * attrs, Value & v)
                 drv.outputs.insert_or_assign(i,
                     DerivationOutput::Impure {
                         .method = method,
-                        .hashAlgo = ht,
+                        .hashAlgo = ha,
                     });
             else
                 drv.outputs.insert_or_assign(i,
                     DerivationOutput::CAFloating {
                         .method = method,
-                        .hashAlgo = ht,
+                        .hashAlgo = ha,
                     });
         }
     }
@@ -3837,7 +3837,7 @@ static RegisterPrimOp primop_convertHash({
 
         The format of the resulting hash. Must be one of
         - `"base16"`
-        - `"base32"`
+        - `"nix32"`
         - `"base64"`
         - `"sri"`
 
diff --git a/src/nix/hash.cc b/src/nix/hash.cc
index 2c9deb0d5..0bba3b7d2 100644
--- a/src/nix/hash.cc
+++ b/src/nix/hash.cc
@@ -118,7 +118,7 @@ struct CmdToBase : Command
 
     std::string description() override
     {
-        return fmt("convert a hash to %s representation",
+        return fmt("convert a hash to %s representation (deprecated, use `nix hash convert` instead)",
             hashFormat == HashFormat::Base16 ? "base-16" :
             hashFormat == HashFormat::Nix32 ? "base-32" :
             hashFormat == HashFormat::Base64 ? "base-64" :