From 435348aa61f28a73c53500de9674183da0117983 Mon Sep 17 00:00:00 2001 From: Stefan Holderbach Date: Mon, 14 Aug 2023 21:17:31 +0200 Subject: [PATCH] Rename misused "deprecation" to removal (#10000) # Description In the past we named the process of completely removing a command and providing a basic error message pointing to the new alternative "deprecation". But this doesn't match the expectation of most users that have seen deprecation _warnings_ that alert to either impending removal or discouraged use after a stability promise. # User-Facing Changes Command category changed from `deprecated` to `removed` --- crates/nu-command/src/default_context.rs | 2 +- crates/nu-command/src/lib.rs | 4 ++-- .../src/{deprecated => removed}/format.rs | 10 +++----- .../src/{deprecated => removed}/let_env.rs | 6 ++--- .../src/{deprecated => removed}/mod.rs | 4 ++-- .../removed_commands.rs} | 6 ++--- crates/nu-command/src/system/run_external.rs | 10 ++++---- crates/nu-command/tests/main.rs | 4 ++-- crates/nu-engine/src/documentation.rs | 6 ++--- crates/nu-protocol/src/engine/engine_state.rs | 5 ++-- crates/nu-protocol/src/shell_error.rs | 23 ++++--------------- crates/nu-protocol/src/signature.rs | 4 ++-- 12 files changed, 33 insertions(+), 51 deletions(-) rename crates/nu-command/src/{deprecated => removed}/format.rs (83%) rename crates/nu-command/src/{deprecated => removed}/let_env.rs (86%) rename crates/nu-command/src/{deprecated => removed}/mod.rs (62%) rename crates/nu-command/src/{deprecated/deprecated_commands.rs => removed/removed_commands.rs} (66%) diff --git a/crates/nu-command/src/default_context.rs b/crates/nu-command/src/default_context.rs index fa364645d4..a3422179a9 100644 --- a/crates/nu-command/src/default_context.rs +++ b/crates/nu-command/src/default_context.rs @@ -374,7 +374,7 @@ pub fn add_shell_command_context(mut engine_state: EngineState) -> EngineState { IsAdmin, }; - // Deprecated + // Removed bind_command! { LetEnv, DateFormat, diff --git a/crates/nu-command/src/lib.rs b/crates/nu-command/src/lib.rs index 1d9b2727cb..f694822fb4 100644 --- a/crates/nu-command/src/lib.rs +++ b/crates/nu-command/src/lib.rs @@ -3,7 +3,6 @@ mod conversions; mod date; mod debug; mod default_context; -mod deprecated; mod env; mod example_test; mod experimental; @@ -21,6 +20,7 @@ mod path; mod platform; mod progress_bar; mod random; +mod removed; mod shells; mod sort_utils; mod strings; @@ -32,7 +32,6 @@ pub use conversions::*; pub use date::*; pub use debug::*; pub use default_context::*; -pub use deprecated::*; pub use env::*; #[cfg(test)] pub use example_test::test_examples; @@ -50,6 +49,7 @@ pub use network::*; pub use path::*; pub use platform::*; pub use random::*; +pub use removed::*; pub use shells::*; pub use sort_utils::*; pub use strings::*; diff --git a/crates/nu-command/src/deprecated/format.rs b/crates/nu-command/src/removed/format.rs similarity index 83% rename from crates/nu-command/src/deprecated/format.rs rename to crates/nu-command/src/removed/format.rs index 9562ca08bf..de5349eaef 100644 --- a/crates/nu-command/src/deprecated/format.rs +++ b/crates/nu-command/src/removed/format.rs @@ -23,15 +23,11 @@ impl Command for SubCommand { SyntaxShape::String, "the desired date format", ) - .category(Category::Date) + .category(Category::Removed) } fn usage(&self) -> &str { - "Format a given date using a format string." - } - - fn search_terms(&self) -> Vec<&str> { - vec!["fmt", "strftime"] + "Removed command: use `format date` instead" } fn run( @@ -41,7 +37,7 @@ impl Command for SubCommand { call: &Call, _input: PipelineData, ) -> Result { - Err(nu_protocol::ShellError::DeprecatedCommand( + Err(nu_protocol::ShellError::RemovedCommand( self.name().to_string(), "format date".to_owned(), call.head, diff --git a/crates/nu-command/src/deprecated/let_env.rs b/crates/nu-command/src/removed/let_env.rs similarity index 86% rename from crates/nu-command/src/deprecated/let_env.rs rename to crates/nu-command/src/removed/let_env.rs index f7eac58ad9..51de55a947 100644 --- a/crates/nu-command/src/deprecated/let_env.rs +++ b/crates/nu-command/src/removed/let_env.rs @@ -20,11 +20,11 @@ impl Command for LetEnv { SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)), "equals sign followed by value", ) - .category(Category::Deprecated) + .category(Category::Removed) } fn usage(&self) -> &str { - "`let-env FOO = ...` is deprecated, use `$env.FOO = ...` instead." + "`let-env FOO = ...` has been removed, use `$env.FOO = ...` instead." } fn run( @@ -34,7 +34,7 @@ impl Command for LetEnv { call: &Call, _: PipelineData, ) -> Result { - Err(nu_protocol::ShellError::DeprecatedCommand( + Err(nu_protocol::ShellError::RemovedCommand( self.name().to_string(), "$env. = ...".to_owned(), call.head, diff --git a/crates/nu-command/src/deprecated/mod.rs b/crates/nu-command/src/removed/mod.rs similarity index 62% rename from crates/nu-command/src/deprecated/mod.rs rename to crates/nu-command/src/removed/mod.rs index 9d4afc642a..5ea783d9ca 100644 --- a/crates/nu-command/src/deprecated/mod.rs +++ b/crates/nu-command/src/removed/mod.rs @@ -1,7 +1,7 @@ -mod deprecated_commands; mod format; mod let_env; +mod removed_commands; -pub use deprecated_commands::*; pub use format::SubCommand as DateFormat; pub use let_env::LetEnv; +pub use removed_commands::*; diff --git a/crates/nu-command/src/deprecated/deprecated_commands.rs b/crates/nu-command/src/removed/removed_commands.rs similarity index 66% rename from crates/nu-command/src/deprecated/deprecated_commands.rs rename to crates/nu-command/src/removed/removed_commands.rs index 7a9e9a33e2..29d32d5e03 100644 --- a/crates/nu-command/src/deprecated/deprecated_commands.rs +++ b/crates/nu-command/src/removed/removed_commands.rs @@ -1,10 +1,10 @@ use std::collections::HashMap; -/// Return map of -/// This covers simple deprecated commands nicely, but it's not great for deprecating +/// Return map of +/// This covers simple removed commands nicely, but it's not great for deprecating /// subcommands like `foo bar` where `foo` is still a valid command. /// For those, it's currently easiest to have a "stub" command that just returns an error. -pub fn deprecated_commands() -> HashMap { +pub fn removed_commands() -> HashMap { [ ("fetch".to_string(), "http get".to_string()), ("post".to_string(), "http post".to_string()), diff --git a/crates/nu-command/src/system/run_external.rs b/crates/nu-command/src/system/run_external.rs index e675ad86da..f0726cef0f 100644 --- a/crates/nu-command/src/system/run_external.rs +++ b/crates/nu-command/src/system/run_external.rs @@ -295,15 +295,15 @@ impl ExternalCommand { match err.kind() { // If file not found, try suggesting alternative commands to the user std::io::ErrorKind::NotFound => { - // recommend a replacement if the user tried a deprecated command + // recommend a replacement if the user tried a removed command let command_name_lower = self.name.item.to_lowercase(); - let deprecated = crate::deprecated_commands(); - if deprecated.contains_key(&command_name_lower) { - let replacement = match deprecated.get(&command_name_lower) { + let removed_from_nu = crate::removed_commands(); + if removed_from_nu.contains_key(&command_name_lower) { + let replacement = match removed_from_nu.get(&command_name_lower) { Some(s) => s.clone(), None => "".to_string(), }; - return Err(ShellError::DeprecatedCommand( + return Err(ShellError::RemovedCommand( command_name_lower, replacement, self.name.span, diff --git a/crates/nu-command/tests/main.rs b/crates/nu-command/tests/main.rs index b10090b230..0e51941dbf 100644 --- a/crates/nu-command/tests/main.rs +++ b/crates/nu-command/tests/main.rs @@ -65,8 +65,8 @@ fn commands_declare_input_output_types() { let sig_name = cmd.signature().name; let category = cmd.signature().category; - if matches!(category, Category::Deprecated | Category::Custom(_)) { - // Deprecated commands don't have to conform + if matches!(category, Category::Removed | Category::Custom(_)) { + // Deprecated/Removed commands don't have to conform // TODO: also upgrade the `--features dataframe` commands continue; } diff --git a/crates/nu-engine/src/documentation.rs b/crates/nu-engine/src/documentation.rs index a6b22f60bd..494d2c4017 100644 --- a/crates/nu-engine/src/documentation.rs +++ b/crates/nu-engine/src/documentation.rs @@ -1,7 +1,7 @@ use nu_protocol::{ ast::Call, engine::{EngineState, Stack}, - Example, IntoPipelineData, PipelineData, Signature, Span, SyntaxShape, Value, + Category, Example, IntoPipelineData, PipelineData, Signature, Span, SyntaxShape, Value, }; use std::{collections::HashMap, fmt::Write}; @@ -94,8 +94,8 @@ fn get_documentation( let signatures = engine_state.get_signatures(true); for sig in signatures { if sig.name.starts_with(&format!("{cmd_name} ")) - // Don't display deprecated commands in the Subcommands list - && !sig.usage.starts_with("Deprecated command") + // Don't display removed/deprecated commands in the Subcommands list + && !matches!(sig.category, Category::Removed) { subcommands.push(format!(" {C}{}{RESET} - {}", sig.name, sig.usage)); } diff --git a/crates/nu-protocol/src/engine/engine_state.rs b/crates/nu-protocol/src/engine/engine_state.rs index 5e8dbb5e61..9c1338cd4c 100644 --- a/crates/nu-protocol/src/engine/engine_state.rs +++ b/crates/nu-protocol/src/engine/engine_state.rs @@ -713,7 +713,7 @@ impl EngineState { for decl in &overlay_frame.decls { if overlay_frame.visibility.is_decl_id_visible(decl.1) && predicate(decl.0) { let command = self.get_decl(*decl.1); - if ignore_deprecated && command.signature().category == Category::Deprecated { + if ignore_deprecated && command.signature().category == Category::Removed { continue; } output.push((decl.0.clone(), Some(command.usage().to_string()))); @@ -1713,8 +1713,7 @@ impl<'a> StateWorkingSet<'a> { for decl in &overlay_frame.decls { if overlay_frame.visibility.is_decl_id_visible(decl.1) && predicate(decl.0) { let command = self.get_decl(*decl.1); - if ignore_deprecated && command.signature().category == Category::Deprecated - { + if ignore_deprecated && command.signature().category == Category::Removed { continue; } output.push((decl.0.clone(), Some(command.usage().to_string()))); diff --git a/crates/nu-protocol/src/shell_error.rs b/crates/nu-protocol/src/shell_error.rs index 9974a43c6f..2f9acb07d3 100644 --- a/crates/nu-protocol/src/shell_error.rs +++ b/crates/nu-protocol/src/shell_error.rs @@ -982,30 +982,17 @@ pub enum ShellError { #[diagnostic()] OutsideSpannedLabeledError(#[source_code] String, String, String, #[label("{2}")] Span), - /// Attempted to use a deprecated command. + /// Attempted to use a command that has been removed from Nushell. /// /// ## Resolution /// /// Check the help for the new suggested command and update your script accordingly. - #[error("Deprecated command {0}")] - #[diagnostic(code(nu::shell::deprecated_command))] - DeprecatedCommand( + #[error("Removed command: {0}")] + #[diagnostic(code(nu::shell::removed_command))] + RemovedCommand( String, String, - #[label = "'{0}' is deprecated. Please use '{1}' instead."] Span, - ), - - /// Attempted to use a deprecated parameter. - /// - /// ## Resolution - /// - /// Check the help for the command and update your script accordingly. - #[error("Deprecated parameter {0}")] - #[diagnostic(code(nu::shell::deprecated_command))] - DeprecatedParameter( - String, - String, - #[label = "Parameter '{0}' is deprecated. Please use '{1}' instead."] Span, + #[label = "'{0}' has been removed from Nushell. Please use '{1}' instead."] Span, ), /// Non-Unicode input received. diff --git a/crates/nu-protocol/src/signature.rs b/crates/nu-protocol/src/signature.rs index 5689692aa0..e054378730 100644 --- a/crates/nu-protocol/src/signature.rs +++ b/crates/nu-protocol/src/signature.rs @@ -49,7 +49,7 @@ pub enum Category { Date, Debug, Default, - Deprecated, + Removed, Env, Experimental, FileSystem, @@ -81,7 +81,7 @@ impl std::fmt::Display for Category { Category::Date => "date", Category::Debug => "debug", Category::Default => "default", - Category::Deprecated => "deprecated", + Category::Removed => "removed", Category::Env => "env", Category::Experimental => "experimental", Category::FileSystem => "filesystem",