Adding a command to the global namespace post 1.0 is a breaking change

[sholderbach]

After our 1.0 release where we want to promise stability to our users the addition of a new command to the global namespace can break existing code of users if they rely on an external command with the same name.

Example

Code uses the stat command from the GNU/coreutils. Post 1.0 the Nushell team decides they want to provide the functionality with rich structured data as our own stat command. Now code running stat will return structured data instead of the existing external stream. Sadness ensues if we think the new command is so important that it should be part of the standard namespace.

Possible mitigations

1. Only allow the addition of new commands to modules that Nushell provides and have to be imported manually. We have existing precedent in the std module (just containing command implementations written in Nu and no Rust builtins). For this you need to use std. For new modules the same concern would apply so they either have to be shipped with 1.0 or be a submodule of an already reserved module.
2. If we decide to reimplement an existing coreutil we could match relevant flags and output behavior to be able to provide the same functionality with limited Nushell specific extensions to minimize breakage (for some users this could still very well be a breaking change

Non-issues (with current design)

Adding a command to the default namespace is not breaking if the user only relies on a custom command, as they currently are able to shadow non-keyword commands. But this is no vindication as arbitrary names could be external executables a user relies on.

[devyn]

One idea I had for this was to only allow external commands without ^ to be used from the REPL, and require it in scripts (including config)

I don't know if that's for sure what we want, but this is definitely an issue I already ran into with someone not being so happy about tee being shadowed

[WindSoilder]

Maybe we can introduce a new prelude module, currently std is implemented in nushell. And I don't think mixing std and new commands after 1.0 is a good idea.

We can have a new flag like --load-prelude to load prelude commands to global namespace when running nushell(which is disabled by default)

[YizhePKU]

Random idea: maybe we can take inspiration from Rust's "edition" system. Each file should declare the Nushell edition it wants, and we can disable newly-introduced commands or keywords based on that.

[sholderbach]

I think the solution we come up with should impose the smallest burden on our users to get the stability after 1.0 (before like with tee not so much).

Random idea: maybe we can take inspiration from Rust's "edition" system. Each file should declare the Nushell edition it wants, and we can disable newly-introduced commands or keywords based on that.

For smaller single-file scripts keeping that metadata around sounds like some extra ceremony, but we could hash out some niches where it might make sense to have a compatibility layer like that. An edition system means we still have to keep old behavior around and (if we promise to) keep it compatible with new behavior along some dimension.

One idea I had for this was to only allow external commands without ^ to be used from the REPL, and require it in scripts (including config)

To me that sounds like a high burden on users to keep life for developers easy that develop either builtins or conflicting Nushell reimplementations, and makes a pretty severe distinction between REPL and script/module.

We can have a new flag like --load-prelude to load prelude commands to global namespace when running nushell(which is disabled by default)

Also feels like a way to push the burden on users and I don't want more confusing flags on nu

Maybe we can introduce a new prelude module, currently std is implemented in nushell. And I don't think mixing std and new commands after 1.0 is a good idea.

While std-library currently is our internal codename for "rewrite it in Nushell" I am not sure if we want to keep this distinction up forever and should for user convenience share module namespaces between Rust-builtins and factory-shipped Nu code.
Imagine if post-1.0 we realize an std command is heavily in use and would benefit from a rewrite in rust for better performance. If we separate the two we would have to slowly deprecate and migrate. If the module namespace could be shared it would be a drop in benefit.

[YizhePKU]

For smaller single-file scripts keeping that metadata around sounds like some extra ceremony

Maybe let the user declare a default edition in their config.nu? Individual scripts can still override it if needed.

An edition system means we still have to keep old behavior around and (if we promise to) keep it compatible with new behavior along some dimension.

If we're just adding new commands, it should be managable. Adding keywords might be tough though.