From 39d26816fe2732546828c769362b4a13a471d674 Mon Sep 17 00:00:00 2001
From: daniel-wong-dfinity-org
 <97631336+daniel-wong-dfinity-org@users.noreply.github.com>
Date: Tue, 3 Sep 2024 19:01:19 +0200
Subject: [PATCH] docs(nns): Small corrections in nns-tools. (#1279)

# Changes

1. README:

1. Refactored instructions for how to do upgrade test. One additional
piece of information: it takes about 5 minutes to run. (If it takes much
longer, operator should start start suspecting that something is wrong,
and begin investigating.)

2. `pkcs11-tool --login --test` (not just `--list-slots`) is a stronger
way to test HSM key, because it prompts for PIN, not just that you can
talk to the hardware.

    3. Removed some recently obsolete information.

2. Generating NNS proposal text: corrections in the section about
argument verification.
---
 testnet/tools/nns-tools/README.md           | 27 ++++++++++-----------
 testnet/tools/nns-tools/lib/proposals.sh    |  4 +--
 testnet/tools/nns-tools/list-new-commits.sh |  2 ++
 3 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/testnet/tools/nns-tools/README.md b/testnet/tools/nns-tools/README.md
index 28abb2fa19c..80157d05940 100644
--- a/testnet/tools/nns-tools/README.md
+++ b/testnet/tools/nns-tools/README.md
@@ -26,9 +26,13 @@ my_useful_function() {
 
 ## Upgrade Testing via Bazel
 
-TL;DR:
-
 ```
+# Run from the usual place.
+ssh -A devenv
+cd src/ic
+./gitlab-ci/container/container-run.sh
+
+# Within the container.
 bazel test \
     --test_env=SSH_AUTH_SOCK \
     --test_env=NNS_CANISTER_UPGRADE_SEQUENCE=all \
@@ -37,16 +41,10 @@ bazel test \
     //rs/nns/integration_tests:upgrade_canisters_with_golden_nns_state
 ```
 
-This is a new way of doing upgrade/release testing (as of May 2024). (The old way is still
-documented elsewhere in this README.)
-
-Perform these instructions from the usual place:
+This takes about 5 min on my devenv.
 
-```
-ssh -A devenv
-cd src/ic
-./gitlab-ci/container/container-run.sh
-```
+(This is a new way of doing upgrade/release testing (as of May 2024). The old way is still
+documented elsewhere in this README.)
 
 One special requirement for this to work is access to zh1-pyr07. This can be
 requested from the consensus team, e.g. Christian Müller.
@@ -448,6 +446,9 @@ Optionally, you can test that your security hardware is ready by running
 
 ```bash
 pkcs11-tool --list-slots
+
+# If you want to practice entering your password:
+pkcs11-tool --login --test
 ```
 
 Finally, run
@@ -478,9 +479,7 @@ For example:
 
 The script validates your proposal text. Specifically, it enforces the following requirements:
 
-1. The proposed canister ID is consistent with the human-readable canister name in the title.
-2. The hash in the proposal matches the hash of the WASM generated for that git version.
-3. There are no TODO items left in the proposal text.
+1. There are no TODO items left in the proposal text.
 
 If your proposal text checks out, the script then prompts you for your HSM pin.
 
diff --git a/testnet/tools/nns-tools/lib/proposals.sh b/testnet/tools/nns-tools/lib/proposals.sh
index fc83bcba0c7..4bd1d22bae6 100644
--- a/testnet/tools/nns-tools/lib/proposals.sh
+++ b/testnet/tools/nns-tools/lib/proposals.sh
@@ -157,11 +157,11 @@ This should match \`wasm_module\` field of this proposal.$(if [ ! -z "$CANDID_AR
 [latest-didc]: https://github.com/dfinity/candid/releases/latest
 
 \`\`\`
-didc encode '$CANDID_ARGS' | xxd -r -p | sha256sum
+didc encode '$CANDID_ARGS'
 
 \`\`\`
 
-This should match the \`arg_hash\` field of this proposal.
+This should match the \`arg_hex\` field of this proposal.
 "
         fi)
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
diff --git a/testnet/tools/nns-tools/list-new-commits.sh b/testnet/tools/nns-tools/list-new-commits.sh
index b35875abb74..b6d330054e7 100755
--- a/testnet/tools/nns-tools/list-new-commits.sh
+++ b/testnet/tools/nns-tools/list-new-commits.sh
@@ -41,6 +41,8 @@ for canister_name in "${NNS_CANISTERS[@]}"; do
     git --no-pager log --format="%C(auto) %h %s" "$released_commit_id".."$RELEASE_CANDIDATE_COMMIT_ID" -- $root
 done
 
+echo
+echo
 echo SNS
 echo =====