From e25df3dd7a149e12562f405114461589472268a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Bidoul?= <stephane.bidoul@gmail.com>
Date: Wed, 28 Dec 2022 12:13:16 +0100
Subject: [PATCH] Clarify the role of the egg URL fragment

---
 docs/html/topics/vcs-support.md | 17 ++++++++++++-----
 news/11676.doc.rst              |  2 ++
 2 files changed, 14 insertions(+), 5 deletions(-)
 create mode 100644 news/11676.doc.rst

diff --git a/docs/html/topics/vcs-support.md b/docs/html/topics/vcs-support.md
index 70bb5beb9dc..07a305cb9e7 100644
--- a/docs/html/topics/vcs-support.md
+++ b/docs/html/topics/vcs-support.md
@@ -136,12 +136,13 @@ option.
 
 ## URL fragments
 
-pip looks at 2 fragments for VCS URLs:
+pip looks at the `subdirectory` fragments for VCS URLs for specifying the path to the
+Python package, when it is not in the root of the VCS directory. eg: `pkg_dir`.
 
-- `egg`: For specifying the "project name" for use in pip's dependency
-  resolution logic. eg: `egg=project_name`
-- `subdirectory`: For specifying the path to the Python package, when it is not
-  in the root of the VCS directory. eg: `pkg_dir`
+pip also looks at the `egg` fragment specifying the "project name". In practice the
+`egg` fragment is only required to help pip determine the VCS clone location in editable
+mode. In all other circumstances, the `egg` fragment is not necessary and its use is
+discouraged.
 
 ````{admonition} Example
 If your repository layout is:
@@ -157,6 +158,12 @@ some_other_file
 
 Then, to install from this repository, the syntax would be:
 
+```{pip-cli}
+$ pip install "pkg @ vcs+protocol://repo_url/#subdirectory=pkg_dir"
+```
+
+or:
+
 ```{pip-cli}
 $ pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
 ```
diff --git a/news/11676.doc.rst b/news/11676.doc.rst
new file mode 100644
index 00000000000..d3f9bd88bed
--- /dev/null
+++ b/news/11676.doc.rst
@@ -0,0 +1,2 @@
+Clarify that the egg URL fragment is only necessary for editable VCS installs, and
+otherwise not necessary anymore.