DO NOT MERGE - based on composite-proposal branch. Once that goes in, rebase from 5b07908e013864631779c9a2abde0d6f40eadaa4 feat(ic-admin): Added --snapshot-before to upgrades.

[daniel-wong-dfinity-org]

More precisely, this is part of propose-to-change-nns-canister (which, btw is a horrible name).

This new flag has an advanced mode: by doing --snapshot-before=replace=${SNAPSHOT_ID}, you can make the new snapshot supplant a pre-existing one.

Makes use of the new Batch proposal type. First, TakeCanisterSnapshot is used. Then, InstallCode (like when the new flag is not used).

Written with Claude.

References.

Closes NNS1-4307.

[github-actions]

This pull request changes code owned by the Governance team. Therefore, make sure that
you have considered the following (for Governance-owned code):

1. Update unreleased_changelog.md (if there are behavior changes, even if they are
   non-breaking).

2. Are there BREAKING changes?

3. Is a data migration needed?

4. Security review?

How to Satisfy This Automatic Review

1. Go to the bottom of the pull request page.

2. Look for where it says this bot is requesting changes.

3. Click the three dots to the right.

4. Select "Dismiss review".

5. In the text entry box, respond to each of the numbered items in the previous
   section, declare one of the following:

• Done.

• $REASON_WHY_NO_NEED. E.g. for unreleased_changelog.md, "No
  canister behavior changes.", or for item 2, "Existing APIs
  behave as before.".

Brief Guide to "Externally Visible" Changes

"Externally visible behavior change" is very often due to some NEW canister API.

Changes to EXISTING APIs are more likely to be "breaking".

If these changes are breaking, make sure that clients know how to migrate, how to
maintain their continuity of operations.

If your changes are behind a feature flag, then, do NOT add entrie(s) to
unreleased_changelog.md in this PR! But rather, add entrie(s) later, in the PR
that enables these changes in production.

Reference(s)

For a more comprehensive checklist, see here.

GOVERNANCE_CHECKLIST_REMINDER_DEDUP

[jasonz-dfinity]

Nit: would it make sense to add an additional flag --replace_snapshot, to be consistent with the TakeSnapshot proposal? I think the complexity from having an additional format ("replace=...") isn't worth the benefit of having one fewer argument.

[daniel-wong-dfinity-org]

Yeah, I thought about that originally. What I don't want is for people to HAVE to supply both. I guess one way is to make --snapshot-before optional (but not banned either) when --replace-snapshot is used. So, supplying both would be supported, but not required.

Another approach is

1. --snapshot-before=without-replacement (instead of just --snapshot-before) vs.
2. --snapshot-before=replace=${ID} (same as what I sent out originally)

Then, it is more symmetrical. WDYT?

I just kind of hate how --snapshot-before and --replace-snapshot heavily overlap (e.g. when using --replace-snapshot, is --snapshot-before REQUIRED??).

OTOH, I understand how replace=${ID} (which results in having two = in one argv element) is a bit ugly; OTOH, that's not unheard of. E.g. in bazel there's --test_env=ENV=VALUE.

FWIW, --snapshot-before replace=${ID} is equivalent to --snapshot-before=replace=${ID}, so at least you do not see two = in one argv.