readme chapter about keyring problems

README.txt

@@ -125,7 +125,9 b' details.'
         default-keyring=keyring.backends.Gnome.Keyring
         # default-keyring=keyring.backends.kwallet.Keyring
 
-   For list of known backends run ``pydoc keyring.backends``.
+   For list of known backends run ``pydoc keyring.backends`` or
+   ``keyring --list-backends`` (which of those commands work,
+   depends on the keyring_ version).
 
 
 ``hgrc`` configuration (HTTP)
@@ -320,6 +322,61 b' The extension is monkey-patching the mer'
 to replace the ``find_user_password`` method. Detailed order of operations
 is described in the comments inside `the code`_.
 
+Frequent problems
+=======================================================
+
+Most problems people face while using ``mercurial_keyring`` are in
+fact problems with ``keyring`` library and it's backends. In
+particular, those can manifest by:
+
+- technical errors mentioning sentences like ``No recommended backend
+  was available. Install the keyrings.alt package…`` (or similar),
+
+- password prompts on every action (= passwords not being saved).
+
+Those almost always mean that *natural* keyring backend for given
+desktop type doesn't work, or is not present at all.  For example,
+some necessary runtime component can be down (say, you use Linux, but
+have neither Gnome Keyring, nor KDE Wallet, running). Or appropriate
+backend is not installed because it could not be build during
+keyring_ library installation (maybe because some required library
+was not present at the moment of keyring installation, or maybe because compiler
+as such is not present on the system).
+
+To diagnose such problems, try using ``keyring`` utility, as described
+on keyring_ documentation page, for example by::
+
+    keyring --list-backends
+    keyring -b keyrings.alt.Gnome.Keyring set testsvc testuser
+    keyring -b keyrings.alt.Gnome.Keyring get testsvc testuser
+
+(of course using appropriate backend). If you miss the ``keyring`` command
+as such, try ``python -m keyring`` instead::
+
+    python -m keyring --list-backends
+    python -m keyring -b keyrings.alt.Gnome.Keyring set testsvc testuser
+    python -m keyring -b keyrings.alt.Gnome.Keyring get testsvc testuser
+
+If appropriate backend is missing (not listed), or doesn't work
+(second or third command fails), your keyring is broken. Try looking
+for further pointers in keyring_ documentation, that project mailing
+list, or issue tracker. Typically it will turn out, that you need to
+install some missing tool, or library, and reinstall keyring.
+
+If ``keyring`` command works, but mercurial with mercurial_keyring does not,
+try enforcing  proper backend (by means of ``keyringrc.cfg``, see above).
+Only if this doesn't help, there may be a bug in mercurial_keyring.
+
+.. note::
+
+   By far easiest way to have properly working keyring is to use
+   packaged binary version (like ``python-keyring`` Ubuntu package, or
+   keyring bundled with TortoiseHG on some systems). If you pip-installed
+   keyring and it doesn't work, you may consider ``pip uninstall keyring``
+   and look for binary package instead.
+
+
+
 History
 =======================================================