Correct user-facing Conda terminology

Author: jezdez

README.md

@@ -47,21 +47,24 @@ supported and will result in an error.
 To check if your base environment is protected, run:
 
 ```
-conda doctor base-protection
+conda doctor -n base base-protection
 ```
 
 To protect your base environment, run:
 
 ```
-conda doctor base-protection --fix
+conda doctor -n base base-protection --fix
 ```
 
 This will:
-1. Clone your current base environment to a new "default" environment
-2. Reset base to conda, conda-self, configured permanent packages, their
-   dependencies, and installed packages named in an available installer
-   snapshot
-3. Mark the base environment as frozen to prevent modifications
+
+1. Try to save a snapshot of base in conda's explicit format
+2. Clone your current base environment to a new "default" environment
+3. Remove conda packages other than conda, conda-self, configured permanent
+   packages, their dependencies, and installed conda packages named in an
+   available installer snapshot
+4. Mark the base environment as frozen so conda refuses modifications by
+   default
 
 To see all available health checks, run:
 
@@ -75,12 +78,13 @@ To remove protection entirely, delete the `conda-meta/frozen` environment
 marker file:
 
 ```
-rm $CONDA_PREFIX/conda-meta/frozen
+rm "$(conda info --base)/conda-meta/frozen"
 ```
 
-To bypass protection for a single command, pass `--override-frozen` or set
-`CONDA_OVERRIDE_FROZEN=1`. To disable it permanently, add `override_frozen: true`
-to your `.condarc`.
+To bypass protection for a single command, pass `--override-frozen`. To disable
+frozen-environment checks through configuration, set
+`CONDA_PROTECT_FROZEN_ENVS=false` or add `protect_frozen_envs: false` to your
+`.condarc`.
 
 ## Configuration
 

conda_self/cli/main_install.py

@@ -16,7 +16,7 @@ def configure_parser(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--force-reinstall",
         action="store_true",
-        help="Reinstall each requested plugin even if it is already installed.",
+        help="Reinstall each requested package even if it is already installed.",
     )
     parser.add_argument("specs", nargs="+", help="Conda plugins to install")
     parser.set_defaults(func=execute)
@@ -44,7 +44,7 @@ def execute(args: argparse.Namespace) -> int:
             "Configure channels via `conda config --add channels <channel>` instead."
         )
 
-    print("Installing plugins:", *args.specs)
+    print("Installing packages:", *args.specs)
 
     returncode = install_specs_in_protected_env(
         args.specs,

conda_self/cli/main_remove.py

@@ -18,10 +18,9 @@ def configure_parser(parser: argparse.ArgumentParser) -> None:
         "--force",
         action="store_true",
         help=(
-            "Remove packages protected from removal because they are permanent "
-            "or dependencies of permanent packages. Permanent packages are "
-            "hard-coded or configured via `plugins.self_permanent_packages`. "
-            "Confirmation is still required unless `--yes` is passed."
+            "Bypass conda-self's check for permanent packages and their "
+            "dependencies. Conda still applies its own transaction checks. "
+            "Confirmation is still required unless --yes is passed."
         ),
     )
     parser.add_argument("specs", nargs="+", help="Conda plugins to remove")
@@ -44,16 +43,15 @@ def execute(args: argparse.Namespace) -> int:
 
     if protected_specs:
         print(
-            "Warning: the following packages are protected from removal "
-            "and will be removed because `--force` was passed:",
+            "Warning: --force bypassed conda-self's check for the following packages:",
             ", ".join(protected_specs),
             file=sys.stderr,
         )
 
-    print("Removing plugins:", *args.specs)
+    print("Removing packages:", *args.specs)
 
     confirm_yn(
-        "Proceed with removing plugins?[y/n]:\n",
+        "Proceed with removing packages?[y/n]:\n",
         default="no",
         dry_run=context.dry_run,
     )

conda_self/cli/main_reset.py

@@ -15,7 +15,7 @@
 class Snapshot(Enum):
     """Snapshot modes accepted by ``conda self reset --snapshot``.
 
-    Plain :class:`enum.Enum` for Python 3.10 compatibility; the string values
+    Plain :class:`enum.Enum` for Python 3.10 compatibility. The string values
     double as argparse choices and user-facing mode names. Switch to
     :class:`enum.StrEnum` when 3.11 becomes the minimum supported version
     (mirrors the TODO on conda's ``EnvironmentFormat``).
@@ -46,7 +46,7 @@ def file_path(self) -> Path | None:
                 return None
 
 
-# Tried in order when --snapshot is not provided; the first mode whose file
+# Tried in order when --snapshot is not provided. The first mode whose file
 # exists on disk wins, otherwise we fall through to CURRENT.
 FALLBACK_ORDER: tuple[Snapshot, ...] = (
     Snapshot.BASE_PROTECTION,
@@ -58,15 +58,16 @@ def file_path(self) -> Path | None:
 SNAPSHOT_HELP = dedent(
     """
     Reset mode for the base environment.
-    `current` removes all packages except for `conda`, `conda-self`, installed
-    conda plugins, configured permanent packages, and their dependencies.
-    `installer` restores the exact packages recorded by the installer and
-    may downgrade updated packages. `installer-exact` is equivalent.
+    `current` removes all conda packages except for `conda`, `conda-self`,
+    installed conda plugins, configured permanent packages, and their
+    dependencies.
+    `installer` restores exactly the conda packages recorded by the installer
+    and may downgrade updated packages. `installer-exact` is equivalent.
     `installer-updated` retains the packages kept by `current` and currently
-    installed packages whose names appear in the installer snapshot. It does
-    not update packages or install missing packages.
-    `base-protection` restores the exact packages recorded by
-    `conda doctor base-protection --fix` before protecting base.
+    installed conda packages whose names appear in the installer snapshot. It
+    does not update packages or install missing packages.
+    `base-protection` restores exactly the conda packages recorded by
+    `conda doctor -n base base-protection --fix` before protecting base.
 
     If not set, `conda self` selects `base-protection` when its snapshot file
     exists, otherwise `installer-updated` when the installer snapshot file
@@ -78,13 +79,13 @@ def file_path(self) -> Path | None:
     """
     This resets the base environment to keep conda, conda-self, installed conda
     plugins, configured permanent packages, and their dependencies.
-    All other packages are removed.
+    All other conda packages are removed.
     """
 ).lstrip()
 WHAT_TO_EXPECT_SNAPSHOT = dedent(
     """
     This resets the base environment using the '{mode_name}' mode
-    and removes packages not retained by that mode.
+    and removes conda packages not retained by that mode.
     """
 ).lstrip()
 SUCCESS = "Reset the base environment using the 'current' mode.\n"
@@ -128,7 +129,7 @@ def execute(args: argparse.Namespace) -> int:
 
     if reset_file is not None and not reset_file.exists():
         raise FileNotFoundError(
-            f"Failed to reset to '{snapshot}'.\nRequired file {reset_file} not found."
+            f"Snapshot file for the '{snapshot}' reset mode not found: {reset_file}"
         )
 
     if not context.json and not context.quiet:

conda_self/exceptions.py

@@ -16,17 +16,21 @@ class NotAPluginError(CondaError):
     def __init__(self, specs: list[str]):
         names = ", ".join(specs)
         if len(specs) == 1:
-            msg = f"The requested package is not a plugin: {names}"
+            msg = f"The requested package is not a conda plugin: {names}"
         else:
-            msg = f"The requested packages are not plugins: {names}"
+            msg = f"The requested packages are not conda plugins: {names}"
         super().__init__(msg)
 
 
 class PluginRemoveError(CondaError):
     def __init__(self, specs: list[str]):
         names = ", ".join(specs)
         noun = _plural("package", len(specs))
-        super().__init__(f"{noun.capitalize()} cannot be removed: {names}")
+        super().__init__(
+            f"conda-self protects the requested {noun} from removal: {names}\n"
+            "Pass --force to bypass this check. Conda's own transaction checks "
+            "still apply."
+        )
 
 
 class NoDistInfoDirFound(CondaError):

conda_self/health_checks/base_protection.py

@@ -46,17 +46,18 @@ def check(prefix: str, _verbose: bool) -> None:
         return
 
     if is_base_protected():
-        print(f"{OK_MARK} Base environment is protected (frozen).\n")
+        print(f"{OK_MARK} Base environment is marked as frozen.\n")
     else:
-        print(f"{X_MARK} Base environment is not protected.\n")
-        print("Run 'conda doctor base-protection --fix' to protect it.\n")
+        print(f"{X_MARK} Base environment is not marked as frozen.\n")
+        print("Run 'conda doctor -n base base-protection --fix' to protect it.\n")
 
 
 def fix(prefix: str, args: Namespace, confirm: ConfirmCallback) -> int:
     """Fix: Protect the base environment.
 
     This clones the base environment to a new 'default' environment,
-    removes packages not retained by base protection, and marks it as frozen.
+    removes conda packages not retained by base protection, and marks it as
+    frozen.
     """
     from pathlib import Path
 
@@ -101,15 +102,21 @@ def fix(prefix: str, args: Namespace, confirm: ConfirmCallback) -> int:
             "and mark it as frozen."
         )
         if env.external_packages:
+            external_package_count = len(env.external_packages)
+            external_package_noun = (
+                "package" if external_package_count == 1 else "packages"
+            )
             print(
-                f"  Warning: Base environment contains {len(env.external_packages)} "
-                "non-conda package(s) that will become non-functional after reset.\n"
+                f"  Warning: Base environment contains {external_package_count} "
+                f"external {external_package_noun} that may no longer work in "
+                "the reset base environment.\n"
                 f"  They are preserved in the cloned '{default_env}' environment."
             )
     confirm("Proceed?")
 
     # Prefer the installer snapshot for resetting base so that
-    # installer-provided packages (e.g. mamba in Miniforge) are preserved.
+    # packages recorded in the installer snapshot (e.g. mamba in Miniforge)
+    # are preserved.
     installer_snapshot = base_prefix / "conda-meta" / RESET_FILE_INSTALLER
     use_snapshot = installer_snapshot.exists()
 
@@ -133,7 +140,10 @@ def fix(prefix: str, args: Namespace, confirm: ConfirmCallback) -> int:
         snapshot_file.write_text(explicit_exporter.export(env))
     except CondaValueError:
         if not context.quiet:
-            print("  Skipping snapshot (non-conda packages present).")
+            print(
+                "  Skipping snapshot because the base environment cannot be "
+                "exported in conda's explicit format."
+            )
 
     if not context.quiet:
         print(f"Cloning the base environment to '{default_env}'...")
@@ -159,7 +169,7 @@ def fix(prefix: str, args: Namespace, confirm: ConfirmCallback) -> int:
         frozen_path = base_prefix / PREFIX_FROZEN_FILE
         frozen_path.write_text(json.dumps({"message": message}) if message else "")
     except OSError as e:
-        raise CondaOSError(f"Could not protect environment: {e}") from e
+        raise CondaOSError(f"Could not protect the base environment: {e}") from e
 
     # Update default activation environment
     if not context.quiet:

conda_self/reset.py

@@ -94,14 +94,14 @@ def records_from_snapshot(
                 spec.get_exact_value("fn") or spec.name for spec in unresolved_specs
             )
             raise CondaError(
-                "Could not download or extract all packages required by the "
-                "selected snapshot.\n"
-                "Required packages:%(packages)s\n"
-                "The target environment was not changed. Some downloaded or "
-                "extracted packages may remain in a package cache. Ensure each "
-                "listed package is available from a package cache or can be "
-                "downloaded from its URL in the snapshot, verified against its "
-                "recorded checksum when present, and extracted, then retry.",
+                "Could not make all conda packages required by the selected "
+                "snapshot available in a package cache.\n"
+                "Required conda packages:%(packages)s\n"
+                "The target environment was not changed. Some conda packages "
+                "may have been downloaded and extracted into a package cache. "
+                "Ensure each listed package is available in a package cache or "
+                "can be downloaded from the URL in the snapshot, verified using "
+                "its recorded checksum when present, and extracted, then retry.",
                 packages=packages,
             ) from None
 
@@ -146,7 +146,8 @@ def reset(
             if not context.json and not context.quiet:
                 print(
                     "Nothing to do. "
-                    "Packages in the target environment match the selected snapshot."
+                    "The conda packages in the target environment match the "
+                    "selected snapshot."
                 )
             return
     else:

demos/base-protection.gif

@@ -16,7 +16,7 @@ Type "# Check if your base environment is protected"
 Enter
 Sleep 500ms
 
-Type@80ms "conda doctor base-protection"
+Type@80ms "conda doctor -n base base-protection"
 Enter
 Wait /\$/
 Sleep 3s
@@ -25,7 +25,7 @@ Type "# Enable protection: clone base, reset, mark as frozen"
 Enter
 Sleep 500ms
 
-Type@80ms "conda doctor base-protection --fix --yes"
+Type@80ms "conda doctor -n base base-protection --fix --yes"
 Enter
 Wait /\$/
 Sleep 3s
@@ -34,7 +34,7 @@ Type "# Verify protection status"
 Enter
 Sleep 500ms
 
-Type@80ms "conda doctor base-protection"
+Type@80ms "conda doctor -n base base-protection"
 Enter
 Wait /\$/
 Sleep 3s