# HG changeset patch
# User Yuya Nishihara <yuya@tcha.org>
# Date 1542030696 -32400
# Node ID 04d08f17ce7a2049476ccf9095af83322fea31a3
# Parent  252396a6a3f2dacecf418925f064ce4ee0a34913
help: document weird behavior of uisetup()

While refactoring ui.log() API, it was really annoying that uisetup() is
actually an extsetup() the phase 1. Let's document that. I'm planning to
add another uisetup() which is called per ui instance, though I can't think
of a good name for it.

diff -r 252396a6a3f2 -r 04d08f17ce7a mercurial/help/internals/extensions.txt
--- a/mercurial/help/internals/extensions.txt	Mon Nov 12 22:26:24 2018 +0900
+++ b/mercurial/help/internals/extensions.txt	Mon Nov 12 22:51:36 2018 +0900
@@ -159,7 +159,8 @@
 then ``extsetup`` is called. This means ``extsetup`` can be useful in case
 one extension optionally depends on another extension.
 
-Both ``uisetup`` and ``extsetup`` receive a ui object::
+Both ``uisetup`` and ``extsetup`` receive a ui object with the local
+repository configuration::
 
     def uisetup(ui):
         # ...
@@ -167,6 +168,13 @@
     def extsetup(ui):
         # ...
 
+Be aware that ``uisetup`` in NOT the function to configure a ``ui`` instance.
+It's called only once per process, not per ``ui`` instance. Also, any changes
+to the ``ui`` may be discarded because the ``ui`` here temporarily loaded
+local configuration. So, it's generally wrong to do `ui.setconfig()` in
+these callbacks. Notable exception is setting ``pre/post-<command>`` hooks
+and extending ``ui.__class__``.
+
 In Mercurial 1.3.1 or earlier, ``extsetup`` takes no argument.
 
 Command table setup