Rewrite some references to "optional groups" (#8454)

## Summary

We generally want to avoid references to "optional groups" now that
dependency groups are a first-class, standardized concept.

Author: charliermarsh

CHANGELOG.md

@@ -1901,8 +1901,7 @@ and `uv tool run` ([#4717](https://github.com/astral-sh/uv/pull/4717))
 - Add `uv tool uninstall` ([#4641](https://github.com/astral-sh/uv/pull/4641))
 - Add support for specifying `name@version` in `uv tool run` ([#4572](https://github.com/astral-sh/uv/pull/4572))
 - Allow `uv add` to specify optional dependency groups ([#4607](https://github.com/astral-sh/uv/pull/4607))
-- Allow the package spec to be passed positionally
-in `uv tool install` ([#4564](https://github.com/astral-sh/uv/pull/4564))
+- Allow the package spec to be passed positionally in `uv tool install` ([#4564](https://github.com/astral-sh/uv/pull/4564))
 - Avoid infinite loop for cyclic installs ([#4633](https://github.com/astral-sh/uv/pull/4633))
 - Indent wheels like dependencies in the lockfile ([#4582](https://github.com/astral-sh/uv/pull/4582))
 - Sync all packages in a virtual workspace ([#4636](https://github.com/astral-sh/uv/pull/4636))

crates/uv-cli/src/lib.rs

@@ -945,7 +945,7 @@ pub struct PipCompileArgs {
     #[arg(long, short, env = EnvVars::UV_BUILD_CONSTRAINT, value_delimiter = ' ', value_parser = parse_maybe_file_path)]
     pub build_constraint: Vec<Maybe<PathBuf>>,
 
-    /// Include optional dependencies from the extra group name; may be provided more than once.
+    /// Include optional dependencies from the specified extra name; may be provided more than once.
     ///
     /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
     #[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)]
@@ -1494,7 +1494,7 @@ pub struct PipInstallArgs {
     #[arg(long, short, env = EnvVars::UV_BUILD_CONSTRAINT, value_delimiter = ' ', value_parser = parse_maybe_file_path)]
     pub build_constraint: Vec<Maybe<PathBuf>>,
 
-    /// Include optional dependencies from the extra group name; may be provided more than once.
+    /// Include optional dependencies from the specified extra name; may be provided more than once.
     ///
     /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
     #[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)]
@@ -2573,7 +2573,7 @@ pub struct InitArgs {
 #[derive(Args)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct RunArgs {
-    /// Include optional dependencies from the extra group name.
+    /// Include optional dependencies from the specified extra name.
     ///
     /// May be provided more than once.
     ///
@@ -2769,7 +2769,7 @@ pub struct RunArgs {
 #[derive(Args)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct SyncArgs {
-    /// Include optional dependencies from the extra group name.
+    /// Include optional dependencies from the specified extra name.
     ///
     /// May be provided more than once.
     ///
@@ -2977,13 +2977,12 @@ pub struct AddArgs {
     #[arg(long, conflicts_with("optional"), conflicts_with("group"))]
     pub dev: bool,
 
-    /// Add the requirements to the specified optional dependency group.
+    /// Add the requirements to the package's optional dependencies for the specified extra.
     ///
     /// The group may then be activated when installing the project with the
     /// `--extra` flag.
     ///
-    /// To enable an optional dependency group for this requirement instead, see
-    /// `--extra`.
+    /// To enable an optional extra for this requirement instead, see `--extra`.
     #[arg(long, conflicts_with("dev"), conflicts_with("group"))]
     pub optional: Option<ExtraName>,
 
@@ -3030,8 +3029,7 @@ pub struct AddArgs {
     ///
     /// May be provided more than once.
     ///
-    /// To add this dependency to an optional group in the current project
-    /// instead, see `--optional`.
+    /// To add this dependency to an optional extra instead, see `--optional`.
     #[arg(long)]
     pub extra: Option<Vec<ExtraName>>,
 
@@ -3101,7 +3099,7 @@ pub struct RemoveArgs {
     #[arg(long, conflicts_with("optional"), conflicts_with("group"))]
     pub dev: bool,
 
-    /// Remove the packages from the specified optional dependency group.
+    /// Remove the packages from the project's optional dependencies for the specified extra.
     #[arg(long, conflicts_with("dev"), conflicts_with("group"))]
     pub optional: Option<ExtraName>,
 
@@ -3282,7 +3280,7 @@ pub struct ExportArgs {
     #[arg(long)]
     pub package: Option<PackageName>,
 
-    /// Include optional dependencies from the extra group name.
+    /// Include optional dependencies from the specified extra name.
     ///
     /// May be provided more than once.
     #[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)]

crates/uv-resolver/src/lock/mod.rs

@@ -3864,7 +3864,7 @@ enum LockErrorKind {
         /// The ID of the package for which a duplicate dependency was
         /// found.
         id: PackageId,
-        /// The name of the optional dependency group.
+        /// The name of the extra.
         extra: ExtraName,
         /// The ID of the conflicting dependency.
         dependency: Dependency,

crates/uv-settings/src/settings.rs

@@ -921,7 +921,7 @@ pub struct PipOptions {
         "#
     )]
     pub strict: Option<bool>,
-    /// Include optional dependencies from the extra group name; may be provided more than once.
+    /// Include optional dependencies from the specified extra; may be provided more than once.
     ///
     /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
     #[option(

docs/concepts/projects.md

@@ -481,7 +481,7 @@ same time.
 uv requires that all optional dependencies ("extras") declared by the project are compatible with
 each other and resolves all optional dependencies together when creating the lockfile.
 
-If optional dependencies declared in one group are not compatible with those in another group, uv
+If optional dependencies declared in one extra are not compatible with those in another extra, uv
 will fail to resolve the requirements of the project with an error.
 
 !!! note
@@ -727,8 +727,8 @@ no-build-isolation-package = ["cchardet"]
 
 Installing packages without build isolation requires that the package's build dependencies are
 installed in the project environment _prior_ to installing the package itself. This can be achieved
-by separating out the build dependencies and the packages that require them into distinct optional
-groups. For example:
+by separating out the build dependencies and the packages that require them into distinct extras.
+For example:
 
 ```toml title="pyproject.toml"
 [project]

docs/reference/cli.md

@@ -136,7 +136,7 @@ uv run [OPTIONS] [COMMAND]
 <p>Accepts both RFC 3339 timestamps (e.g., <code>2006-12-02T02:07:43Z</code>) and local dates in the same format (e.g., <code>2006-12-02</code>) in your system&#8217;s configured time zone.</p>
 
 <p>May also be set with the <code>UV_EXCLUDE_NEWER</code> environment variable.</p>
-</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the extra group name.</p>
+</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name.</p>
 
 <p>May be provided more than once.</p>
 
@@ -743,7 +743,7 @@ uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
 
 <p>May be provided more than once.</p>
 
-<p>To add this dependency to an optional group in the current project instead, see <code>--optional</code>.</p>
+<p>To add this dependency to an optional extra instead, see <code>--optional</code>.</p>
 
 </dd><dt><code>--extra-index-url</code> <i>extra-index-url</i></dt><dd><p>(Deprecated: use <code>--index</code> instead) Extra URLs of package indexes to use, in addition to <code>--index-url</code>.</p>
 
@@ -886,11 +886,11 @@ uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
 
 <p>When disabled, uv will only use locally cached data and locally available files.</p>
 
-</dd><dt><code>--optional</code> <i>optional</i></dt><dd><p>Add the requirements to the specified optional dependency group.</p>
+</dd><dt><code>--optional</code> <i>optional</i></dt><dd><p>Add the requirements to the package&#8217;s optional dependencies for the specified extra.</p>
 
 <p>The group may then be activated when installing the project with the <code>--extra</code> flag.</p>
 
-<p>To enable an optional dependency group for this requirement instead, see <code>--extra</code>.</p>
+<p>To enable an optional extra for this requirement instead, see <code>--extra</code>.</p>
 
 </dd><dt><code>--package</code> <i>package</i></dt><dd><p>Add the dependency to a specific package in the workspace</p>
 
@@ -1222,7 +1222,7 @@ uv remove [OPTIONS] <PACKAGES>...
 
 <p>When disabled, uv will only use locally cached data and locally available files.</p>
 
-</dd><dt><code>--optional</code> <i>optional</i></dt><dd><p>Remove the packages from the specified optional dependency group</p>
+</dd><dt><code>--optional</code> <i>optional</i></dt><dd><p>Remove the packages from the project&#8217;s optional dependencies for the specified extra</p>
 
 </dd><dt><code>--package</code> <i>package</i></dt><dd><p>Remove the dependencies from a specific package in the workspace</p>
 
@@ -1401,7 +1401,7 @@ uv sync [OPTIONS]
 <p>Accepts both RFC 3339 timestamps (e.g., <code>2006-12-02T02:07:43Z</code>) and local dates in the same format (e.g., <code>2006-12-02</code>) in your system&#8217;s configured time zone.</p>
 
 <p>May also be set with the <code>UV_EXCLUDE_NEWER</code> environment variable.</p>
-</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the extra group name.</p>
+</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name.</p>
 
 <p>May be provided more than once.</p>
 
@@ -2029,7 +2029,7 @@ uv export [OPTIONS]
 <p>Accepts both RFC 3339 timestamps (e.g., <code>2006-12-02T02:07:43Z</code>) and local dates in the same format (e.g., <code>2006-12-02</code>) in your system&#8217;s configured time zone.</p>
 
 <p>May also be set with the <code>UV_EXCLUDE_NEWER</code> environment variable.</p>
-</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the extra group name.</p>
+</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name.</p>
 
 <p>May be provided more than once.</p>
 
@@ -4951,7 +4951,7 @@ uv pip compile [OPTIONS] <SRC_FILE>...
 <p>Accepts both RFC 3339 timestamps (e.g., <code>2006-12-02T02:07:43Z</code>) and local dates in the same format (e.g., <code>2006-12-02</code>) in your system&#8217;s configured time zone.</p>
 
 <p>May also be set with the <code>UV_EXCLUDE_NEWER</code> environment variable.</p>
-</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the extra group name; may be provided more than once.</p>
+</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name; may be provided more than once.</p>
 
 <p>Only applies to <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code> sources.</p>
 
@@ -5715,7 +5715,7 @@ uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITAB
 <p>Accepts both RFC 3339 timestamps (e.g., <code>2006-12-02T02:07:43Z</code>) and local dates in the same format (e.g., <code>2006-12-02</code>) in your system&#8217;s configured time zone.</p>
 
 <p>May also be set with the <code>UV_EXCLUDE_NEWER</code> environment variable.</p>
-</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the extra group name; may be provided more than once.</p>
+</dd><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name; may be provided more than once.</p>
 
 <p>Only applies to <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code> sources.</p>
 

docs/reference/settings.md

@@ -1890,7 +1890,7 @@ system's configured time zone.
 #### [`extra`](#pip_extra) {: #pip_extra }
 <span id="extra"></span>
 
-Include optional dependencies from the extra group name; may be provided more than once.
+Include optional dependencies from the specified extra; may be provided more than once.
 
 Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.