From 0bdb796a3b2426f88f83644032d4bda6f7b913b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Randy=20D=C3=B6ring?=
 <30527984+radoering@users.noreply.github.com>
Date: Tue, 13 Jun 2023 18:01:24 +0200
Subject: [PATCH] docs: warn about `self` commands on Windows

---
 docs/_index.md  |  5 +++++
 docs/cli.md     |  7 +++++++
 docs/plugins.md | 55 ++++++++++++++++++++++++++-----------------------
 3 files changed, 41 insertions(+), 26 deletions(-)

diff --git a/docs/_index.md b/docs/_index.md
index 34e0da401ad..06e800ea818 100644
--- a/docs/_index.md
+++ b/docs/_index.md
@@ -212,6 +212,11 @@ If you see something like `Poetry (version 1.2.0)`, your install is ready to use
 
 Poetry is able to update itself when installed using the official installer.
 
+{{% warning %}}
+Especially on Windows, `self update` may be problematic
+so that a re-install with the installer should be preferred.
+{{% /warning %}}
+
 ```bash
 poetry self update
 ```
diff --git a/docs/cli.md b/docs/cli.md
index 81d3f6de93d..7e4eaf4a142 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -889,6 +889,13 @@ Use of these commands will create the required `pyproject.toml` and `poetry.lock
 [configuration directory]({{< relref "configuration" >}}).
 {{% /note %}}
 
+{{% warning %}}
+Especially on Windows, `self` commands that update or remove packages may be problematic
+so that other methods for installing plugins and updating Poetry are recommended.
+See [Using plugins]({{< relref "plugins#using-plugins" >}}) and
+[Installing Poetry]({{< relref "docs#installation" >}}) for more information.
+{{% /warning %}}
+
 ### self add
 
 The `self add` command installs Poetry plugins and make them available at runtime. Additionally, it can
diff --git a/docs/plugins.md b/docs/plugins.md
index 54ee7abc968..d3af23ce363 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -191,32 +191,6 @@ Installed plugin packages are automatically loaded when Poetry starts up.
 
 You have multiple ways to install plugins for Poetry
 
-### The `self add` command
-
-This is the easiest way and should account for all the ways Poetry can be installed.
-
-```bash
-poetry self add poetry-plugin
-```
-
-The `self add` command will ensure that the plugin is compatible with the current version of Poetry
-and install the needed packages for the plugin to work.
-
-The package specification formats supported by the `self add` command are the same as the ones supported
-by the [`add` command]({{< relref "cli#add" >}}).
-
-If you no longer need a plugin and want to uninstall it, you can use the `self remove` command.
-
-```shell
-poetry self remove poetry-plugin
-```
-
-You can also list all currently installed plugins by running:
-
-```shell
-poetry self show plugins
-```
-
 ### With `pipx inject`
 
 If you used `pipx` to install Poetry you can add the plugin packages via the `pipx inject` command.
@@ -250,6 +224,35 @@ If you want to uninstall a plugin, you can run:
 $POETRY_HOME/bin/pip uninstall poetry-plugin
 ```
 
+### The `self add` command
+
+{{% warning %}}
+Especially on Windows, `self add` and `self remove` may be problematic
+so that other methods should be preferred.
+{{% /warning %}}
+
+```bash
+poetry self add poetry-plugin
+```
+
+The `self add` command will ensure that the plugin is compatible with the current version of Poetry
+and install the needed packages for the plugin to work.
+
+The package specification formats supported by the `self add` command are the same as the ones supported
+by the [`add` command]({{< relref "cli#add" >}}).
+
+If you no longer need a plugin and want to uninstall it, you can use the `self remove` command.
+
+```shell
+poetry self remove poetry-plugin
+```
+
+You can also list all currently installed plugins by running:
+
+```shell
+poetry self show plugins
+```
+
 
 ## Maintaining a plugin