changeset 6840:9c70bdc92cdb stable

docs: update installation instructions due to PEP 668

--- a/README.rst	Fri Aug 23 17:00:28 2024 +0400
+++ b/README.rst	Mon Jul 22 15:57:13 2024 +0400
@@ -26,7 +26,7 @@
 * improves performance of obsolescence marker exchange and discovery during
   push and pull.
 
-.. _`changeset evolution`: https://www.mercurial-scm.org/wiki/ChangesetEvolution
+.. _`changeset evolution`: https://wiki.mercurial-scm.org/ChangesetEvolution
 
 Documentation
 -------------
@@ -48,44 +48,101 @@
 
     $ pip install --user hg-evolve
 
-Then enable it in your hgrc::
+Note: some distributions have adopted PEP 668 and made using ``pip install
+--user`` more difficult than it should be. One of the cleanest ways around this
+issue is to install both Mercurial and this extension in a separate virtual
+environment. If you don't want to manage the virtual environment manually, you
+can use Pipx.
+
+Using Pipx
+----------
+
+Its documentation explains that "pipx is made specifically for application
+installation", and the idea is that for every application it can create and
+maintain a separate virtual environment and make all executables available on a
+single path (e.g. ~/.local/bin/ on Linux, check ``pipx ensurepath``).
+
+To create a virtual environment for hg and install evolve::
+
+    $ pipx install mercurial
+    $ pipx inject mercurial hg-evolve
+    # or pipx runpip mercurial install hg-evolve
+
+Note: it's recommended to use ``inject`` command to install evolve, but
+sometimes ``runpip`` could be used. On some setups ``inject`` might require
+specifying the full path to the extension in the configuration file, while
+``runpip`` might not.
+
+Using Your Package Manager
+--------------------------
+
+Sometimes your distribution's package manager might have the newest (or recent
+enough) version of the extension. For example, both `Debian`_ and `Ubuntu`_
+currently have a package called ``mercurial-evolve``.  Similarly, other
+distributions might have it packaged, possibly under a slightly different name.
+Try searching your package manager's database or see `this Repology page`_.
+
+.. _`Debian`: https://packages.debian.org/search?keywords=mercurial-evolve&searchon=names&exact=1&suite=all&section=all
+.. _`Ubuntu`: https://packages.ubuntu.com/search?keywords=mercurial-evolve&searchon=names&exact=1&suite=all&section=all
+.. _`this Repology page`: https://repology.org/project/mercurial-evolve/related
+
+From Source
+-----------
+
+To obtain a local version from source::
+
+    $ hg clone https://repo.mercurial-scm.org/evolve
+
+There's no need to compile anything or run ``make``.
+
+This method keeps the extension in its own repo, and you can use it by
+specifying the full path to the ``hgext3rd/evolve/``.
+
+Alternatively, you can install it::
+
+    $ cd evolve
+    # optionally `hg update <target revision>`
+    $ pip install --user .
+
+This should avoid the need to specify the full path to the extension.
+
+Enabling the Extension
+----------------------
+
+After installing the extension, you need to enable it before you can use it.
+
+To do that, edit your hgrc::
 
     $ hg config --edit # add these two lines:
     [extensions]
     evolve =
 
-From Source
------------
-
-To install a local version from source::
-
-    $ hg clone https://www.mercurial-scm.org/repo/evolve/
-    $ cd evolve
-    # optionally `hg update <target revision>`
-    $ pip install --user .
-
-Then enable it in your hgrc::
-
-    $ hg config --edit # add these two lines:
-    [extensions]
-    evolve =
-
-It's also possible to use evolve without installing it, in which case you will
-need to provide the full path to ``hgext3rd/evolve/``, for example::
+If you didn't install the extension or Mercurial can't find it on one of the
+default paths, you need to specify the full path to ``hgext3rd/evolve/``::
 
     [extensions]
     evolve = ~/evolve/hgext3rd/evolve
 
+Similarly, if you want to enable topic extension, do this::
+
+    $ hg config --edit
+    [extensions]
+    topic =
+    # or
+    topic = ~/evolve/hgext3rd/topic
+
 Pitfalls
 --------
 
 If you get ``"failed to import extension evolve: No module named 'evolve'"``
 error, there are a couple of things to check:
 
-* make sure you gave pip the correct package name (it's hg-evolve),
+* make sure you gave pip/pipx the correct package name (it's ``hg-evolve``),
 
 * make sure evolve is installed for the same version of Python that you use for
-  running Mercurial (``hg debuginstall | grep Python``).
+  running Mercurial (``hg debuginstall | grep Python``),
+
+* try specifying the full path to the ``hgext3rd/evolve/`` directory.
 
 Extension Purpose
 =================
@@ -110,7 +167,7 @@
 Mercurial announced official `support for Python 3`_ starting with its 5.2
 release. Since 9.3.0, evolve has official support for Python 3.6+.
 
-.. _`support for Python 3`: https://www.mercurial-scm.org/wiki/Python3
+.. _`support for Python 3`: https://wiki.mercurial-scm.org/Python3
 
 Python 2 Support
 ================
@@ -146,7 +203,7 @@
 
 For guidelines on the patch description, see the `official Mercurial guideline`_.
 
-.. _`official Mercurial guideline`: https://mercurial-scm.org/wiki/ContributingChanges#Patch_descriptions
+.. _`official Mercurial guideline`: https://wiki.mercurial-scm.org/ContributingChanges#Patch_descriptions
 
 Please don't forget to update and run the tests when you fix a bug or add a
 feature. To run the tests, you need a working copy of Mercurial, say in