nix flake update add deprecation warnings.

[angerman]

This builds on #8817, to add additional UX help for people with existing muscle memory (or shell history) with --update-input and tries to gently guide them towards the newly evolved CLI UI.

Motivation

This change introduces a deprecation warning for the nix flake lock --update-input INPUT command, guiding users towards the newer nix flake update INPUT syntax. The motivation is to enhance user experience by providing clear and helpful guidance when encountering deprecated commands. This change aligns with our ongoing efforts to streamline Nix commands and improve their intuitiveness and ease of use.

Context

Many users familiar with the older nix flake lock --update-input syntax may not be aware of its deprecation and the transition to the new nix flake update command. The current behavior, which results in an unrecognised flag error, can be confusing and does not guide users towards the correct command. By introducing a deprecation warning, we provide a more user-friendly approach, aiding in a smoother transition to the updated syntax.

Example

Before:

bash-5.2$ outputs/out/bin/nix flake lock --update-input libgit2
error: unrecognised flag '--update-input'

After:

bash-5.2$ outputs/out/bin/nix flake lock --recreate-lock-file
warning: '--recreate-lock-file' is deprecated; use 'nix flake update' instead.
warning: Git tree 'nix' is dirty
warning: updating lock file 'nix/flake.lock':

Priorities

Add 👍 to pull requests you find important.

[Ericson2314]

This looks good to me.

(Note for future work) We really need to have some sort of of "deprecated features" which is the dual of "experimental features" to keep track of this stuff.

[grahamc]

We really need to have some sort of of "deprecated features" which is the dual of "experimental features" to keep track of this stuff

I'm heading to bed, but I put one together about a month ago. I can send it over :).

[cole-h]

Couple wording nits, feel free to take or leave them

[Ericson2314]

Oh please do @grahamc. I always greatly appreciate when someone else knocks an item off my to-do list.

[fricklerhandwerk]

This should also show up in documentation.

Suggested change

	.description = "Recreate the flake's lock file from scratch.",
	.description = R"(
	Recreate the flake's lock file from scratch.
	> **DEPRECATED**
	>
	> Use [`nix flake update`](@docroot@/command-ref/new-cli/nix3-flake-update.md) instead.
	)",

Not sure about syntax and if the link is exactly right, but something along these lines.

[github-actions]

Successfully created backport PR for 2.19-maintenance:

• [Backport 2.19-maintenance] nix flake update add deprecation warnings. #9460

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-11-27-nix-team-meeting-minutes-107/36112/1