Adds Nix CLI Guideline to docs #4302
Conversation
As we are working towards Nix 3.0 we want to make sure that we make a huge step forward in Nix's user experience. And once 3.0 is out of the door we need to make sure that all future commands and features keep up the standard of user experience. This PR adds a CLI guideline document to the Nix documentation. Consider this document a good starting point and a checklist when somebody will be (re)implementing commands. Clearly this guideline does nothing to improve user experience on its own and can only be useful as long as it is going to be read and cared for. But it is a first step into that direction.
|
Hmm this takes a sort of "behind the curtains" tone addressing Nix developers not users, though it's in the manual not some |
|
@Ericson2314 Good point. It would be better to put this either in a "developer info" appendix (we do already have "hacking" appendix), or in a separate book (which could also include #4280). |
| `nix` commands. | ||
|
|
||
| ```shell | ||
| $ nix [<GROUP>] <COMMAND> [<ARGUMENTS>] [<OPTIONS>] |
There was a problem hiding this comment.
So I tried to apply this today and realized it's confusing. If nix foo is a command, then what is nix?
Maybe the current terminology ("subcommand") is better.
There was a problem hiding this comment.
nix foo can either be a COMMAND or a GROUP. For example nix store is a GROUP and nix init is a COMMAND and also nix store copy is a COMMAND.
I would call nix top level command, but I don't really care how we call things as long as it is consistent :)
This guideline should only be for the experimental |
|
It's not really about whether this is experimental but about whether it's user-facing, which it isn't - it's only for people who want to contribute to Nix. Let's make an appendix named "Contributing" which can include this and the existing "Hacking" section. |
|
Would it make sense to also introduce the notion of "plumbing" vs "porcelain"? The old-school nix-* CLI is very much plumbing and can be used in all sorts of conditions, which is great. The Nix 2.0 CLI seems to be doing a bit of both. |
Roughly the "utility/scripting commands" (tier 3 in the current doc) are the plumbing. |
to classification to a more descriptive classification.
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/tweag-nix-dev-update-5/10560/1 |
|
There's a piece of similar documentation which I perceive to be missing which is a transition plan from the old to the new cli. I'm looking forward to a better UX but I hope the plan is not "Nix 2.0 has the old cli and the new experimental stuff is discouraged, Nix 3.0 has the new cli and only the new cli." Will there be an acclimatization period where the new cli is no longer marked as experimental and users are encouraged to attempt transitioning without being forced give up on the familiar cli all of a sudden? |
|
The plan is roughly:
|
|
Thanks for the quick response. One more question. Apparently |
|
Currently the new man pages are called |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/tweag-nix-dev-update-6/11195/1 |
As we are working towards Nix 3.0 we want to make sure that we make a
huge step forward in Nix's user experience. And once 3.0 is out of the
door we need to make sure that all future commands and features keep up
the standard of user experience.
This PR adds a CLI guideline document to the Nix documentation. Consider
this document a good starting point and a checklist when somebody will
be (re)implementing commands.
Clearly this guideline does nothing to improve user experience on its
own and can only be useful as long as it is going to be read and
cared for. But it is a first step into that direction.