Patchwork [3,of,3] help: document weird behavior of uisetup()

login
register
mail settings
Submitter Yuya Nishihara
Date Nov. 12, 2018, 2:22 p.m.
Message ID <bc299f37cb3f50104849.1542032525@mimosa>
Download mbox | patch
Permalink /patch/36525/
State Accepted
Headers show

Comments

Yuya Nishihara - Nov. 12, 2018, 2:22 p.m.
# HG changeset patch
# User Yuya Nishihara <yuya@tcha.org>
# Date 1542030696 -32400
#      Mon Nov 12 22:51:36 2018 +0900
# Node ID bc299f37cb3f501048499b39d4fd63b6a5a32902
# Parent  f1ad5eaa63c8f4ac5a9b5c7553d40cc33792a34e
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.

Patch

diff --git a/mercurial/help/internals/extensions.txt b/mercurial/help/internals/extensions.txt
--- a/mercurial/help/internals/extensions.txt
+++ b/mercurial/help/internals/extensions.txt
@@ -159,7 +159,8 @@  There are two callbacks to be called whe
 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 @@  Both ``uisetup`` and ``extsetup`` receiv
     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