Merge pull request #11676 from sbidoul/clarify-egg-fragment-docs-sbi

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"
 ```

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.