fix: add missing deprecation warning for `--dev` (#6475)

`--dev` is marked as deprecated for both
[add](https://python-poetry.org/docs/cli/#options-4) and
[remove](https://python-poetry.org/docs/cli/#options-5) commands in the
documentation and emit a warning when used, but this is not reflected in
the CLI help messages.

I also took the occasion to update the documentation to suggest
replacements. Once backported, this would also require an update of the
1.2.0 blog post announcement, which doesn't mention those deprecations.

docs/cli.md

@@ -235,8 +235,8 @@ poetry install --no-root
 * `--dry-run`: Output the operations but do not execute anything (implicitly enables --verbose).
 * `--dry-run`: Output the operations but do not execute anything (implicitly enables --verbose).
 * `--extras (-E)`: Features to install (multiple values allowed).
 * `--extras (-E)`: Features to install (multiple values allowed).
 * `--all-extras`: Install all extra features (conflicts with --extras).
 * `--all-extras`: Install all extra features (conflicts with --extras).
-* `--no-dev`: Do not install dev dependencies. (**Deprecated**)
-* `--remove-untracked`: Remove dependencies not presented in the lock file. (**Deprecated**)
+* `--no-dev`: Do not install dev dependencies. (**Deprecated**, use `--without dev` or `--only main` instead)
+* `--remove-untracked`: Remove dependencies not presented in the lock file. (**Deprecated**, use `--sync` instead)
 
 
 {{% note %}}
 {{% note %}}
 When `--only` is specified, `--with` and `--without` options are ignored.
 When `--only` is specified, `--with` and `--without` options are ignored.
@@ -271,7 +271,7 @@ update the constraint, for example `^2.3`. You can do this using the `add` comma
 * `--with`: The optional dependency groups to include.
 * `--with`: The optional dependency groups to include.
 * `--only`: The only dependency groups to include.
 * `--only`: The only dependency groups to include.
 * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
 * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
-* `--no-dev` : Do not update the development dependencies. (**Deprecated**)
+* `--no-dev` : Do not update the development dependencies. (**Deprecated**, use `--without dev` or `--only main` instead)
 * `--lock` : Do not perform install (only update the lockfile).
 * `--lock` : Do not perform install (only update the lockfile).
 
 
 {{% note %}}
 {{% note %}}
@@ -409,7 +409,7 @@ about dependency groups.
 ### Options
 ### Options
 
 
 * `--group (-G)`: The group to add the dependency to.
 * `--group (-G)`: The group to add the dependency to.
-* `--dev (-D)`: Add package as development dependency. (**Deprecated**)
+* `--dev (-D)`: Add package as development dependency. (**Deprecated**, use `-G dev` instead)
 * `--editable (-e)`: Add vcs/path dependencies as editable.
 * `--editable (-e)`: Add vcs/path dependencies as editable.
 * `--extras (-E)`: Extras to activate for the dependency. (multiple values allowed)
 * `--extras (-E)`: Extras to activate for the dependency. (multiple values allowed)
 * `--optional`: Add as an optional dependency.
 * `--optional`: Add as an optional dependency.
@@ -442,13 +442,13 @@ about dependency groups.
 ### Options
 ### Options
 
 
 * `--group (-G)`: The group to remove the dependency from.
 * `--group (-G)`: The group to remove the dependency from.
-* `--dev (-D)`: Removes a package from the development dependencies. (**Deprecated**)
+* `--dev (-D)`: Removes a package from the development dependencies. (**Deprecated**, use `-G dev` instead)
 * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
 * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
 
 
 
 
 ## show
 ## show
 
 
-To list all of the available packages, you can use the `show` command.
+To list all the available packages, you can use the `show` command.
 
 
 ```bash
 ```bash
 poetry show
 poetry show
@@ -478,7 +478,7 @@ required by
 * `--why`: When showing the full list, or a `--tree` for a single package, display why a package is included.
 * `--why`: When showing the full list, or a `--tree` for a single package, display why a package is included.
 * `--with`: The optional dependency groups to include.
 * `--with`: The optional dependency groups to include.
 * `--only`: The only dependency groups to include.
 * `--only`: The only dependency groups to include.
-* `--no-dev`: Do not list the dev dependencies. (**Deprecated**)
+* `--no-dev`: Do not list the dev dependencies. (**Deprecated**, use `--without dev` or `--only main` instead)
 * `--tree`: List the dependencies as a tree.
 * `--tree`: List the dependencies as a tree.
 * `--latest (-l)`: Show the latest version.
 * `--latest (-l)`: Show the latest version.
 * `--outdated (-o)`: Show the latest version but only for packages that are outdated.
 * `--outdated (-o)`: Show the latest version but only for packages that are outdated.
@@ -689,7 +689,7 @@ group defined in `tool.poetry.dependencies` when used without specifying any opt
   Currently, only `requirements.txt` is supported.
   Currently, only `requirements.txt` is supported.
 * `--output (-o)`: The name of the output file.  If omitted, print to standard
 * `--output (-o)`: The name of the output file.  If omitted, print to standard
   output.
   output.
-* `--dev`: Include development dependencies. (**Deprecated**)
+* `--dev`: Include development dependencies. (**Deprecated**, use `--with dev` instead)
 * `--extras (-E)`: Extra sets of dependencies to include.
 * `--extras (-E)`: Extra sets of dependencies to include.
 * `--without`: The dependency groups to ignore.
 * `--without`: The dependency groups to ignore.
 * `--with`: The optional dependency groups to include.
 * `--with`: The optional dependency groups to include.

src/poetry/console/commands/add.py

@@ -27,7 +27,11 @@ class AddCommand(InstallerCommand, InitCommand):
             flag=False,
             flag=False,
             default=MAIN_GROUP,
             default=MAIN_GROUP,
         ),
         ),
-        option("dev", "D", "Add as a development dependency."),
+        option(
+            "dev",
+            "D",
+            "Add as a development dependency. (<warning>Deprecated</warning>)",
+        ),
         option("editable", "e", "Add vcs/path dependencies as editable."),
         option("editable", "e", "Add vcs/path dependencies as editable."),
         option(
         option(
             "extras",
             "extras",

src/poetry/console/commands/remove.py

@@ -18,7 +18,12 @@ class RemoveCommand(InstallerCommand):
     arguments = [argument("packages", "The packages to remove.", multiple=True)]
     arguments = [argument("packages", "The packages to remove.", multiple=True)]
     options = [
     options = [
         option("group", "G", "The group to remove the dependency from.", flag=False),
         option("group", "G", "The group to remove the dependency from.", flag=False),
-        option("dev", "D", "Remove a package from the development dependencies."),
+        option(
+            "dev",
+            "D",
+            "Remove a package from the development dependencies."
+            " (<warning>Deprecated</warning>)",
+        ),
         option(
         option(
             "dry-run",
             "dry-run",
             None,
             None,