From 668ea3f6f383749ee9a7a4fdd56246851820e1bb 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 | 24 +++++++++++++++---------
 news/11676.doc.rst              |  2 ++
 2 files changed, 17 insertions(+), 9 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 4c69c4e0228..faa0633cc7f 100644
--- a/docs/html/topics/vcs-support.md
+++ b/docs/html/topics/vcs-support.md
@@ -132,17 +132,17 @@ take on the VCS requirement (not the commit itself).
 
 ## URL fragments
 
-pip looks at 2 fragments for VCS URLs:
+pip looks at the `subdirectory` fragments of 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. e.g.: `egg=project_name`
+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.
 
-  The `egg` fragment **should** be a bare
-  [PEP 508](https://peps.python.org/pep-0508/) project name. Anything else
-  is not guaranteed to work.
-
-- `subdirectory`: For specifying the path to the Python package, when it is not
-  in the root of the VCS directory. e.g.: `pkg_dir`
+The `egg` fragment **should** be a bare
+[PEP 508](https://peps.python.org/pep-0508/) project name. Anything else
+is not guaranteed to work.
 
 ````{admonition} Example
 If your repository layout is:
@@ -158,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.