Differences between revisions 1 and 12 (spanning 11 versions)
Revision 1 as of 2017-01-31 12:43:32
Size: 1977
Comment:
Revision 12 as of 2017-07-13 09:04:23
Size: 5591
Comment:
Deletions are marked like this. Additions are marked like this.
Line 7: Line 7:
<<TableOfContents>>
Line 9: Line 11:
'''Main proponents: DavidDemelier''' '''Main proponents: DavidDemelier,[[Pierre-Yves David]]'''
Line 18: Line 20:
Line 30: Line 31:
=== Proposal: allow _ and - anywhere === In addition, having guideline for sections would be useful. In Mercurial core + bundle extension we have about 300 configuration option. They are spread in the following sections:
Line 32: Line 33:
Since we have a strong backward compatibility concern, I have a proposal that I saw in a software a long time ago. The idea is to allow adding any underscore or hyphens in options and they are simply removed when loaded from the configuration. {{{
     34 ui
     28 convert
     27 experimental
     21 web
     20 bugzilla
     19 lists
     13 notify
     10 format
     10 devel
      9 values
      9 profiling
      7 server
      6 smtp
      5 worker
      5 patchbomb
      5 http_proxy
      4 progress
      4 mq
      3 pager
      3 histedit
      3 factotum
      3 eol
      3 email
      2 transplant
      2 share
      2 phases
      2 paths
      2 patch
      2 merge
      2 hostsecurity
      2 gpg
      2 fsmonitor
      2 color
      2 chgserver
      2 bundle
      2 blackbox
      2 acl
      1 win32text
      1 win32mbcs
      1 shelve
      1 perf
      1 keywordset
      1 hook
      1 hgk
      1 fakepatchtime
      1 fakedirstatewritetime
      1 debug
      1 cmdserver
      1 censor
      1 bookmarks
      1 automv
}}}

There are *many* options is the `[ui]` section and many section with version few config. Gathering related options in the same config section have multiple advantages. The main one is that it gather the related option in the documentation improving discoverability. For the same reason, having too many options is the `[ui]` is drowning the important ones in the help of more minor ones.

==== Proposal: use - in config examples ====

While major options can be written in only one word, we should start using hyphens between words.
Line 37: Line 96:
[ui]
username = blabla
[web]
allow-pull = foo
allow-push = bar
Line 41: Line 101:
Is equivalent to The actual config looks like this:
Line 44: Line 104:
[ui]
user_name = blabla
[web]
allowpull = foo
allow_push = bar # yes, for real

[progress]
assume-tty = yes

[worker]
backgroundcloseminfilecount = 12
Line 48: Line 115:
Or even to Names like '''backgroundcloseminfilecount''', '''graphnodetemplate''', '''mergemarkertemplate''' are actually not readable by humans.

Using the implemented alias support, we can start renaming options to the new convention without any breakage.
Line 51: Line 120:
[ui]
us_er-na_me = blabla
coreconfigitem('web', 'allowpull',
    default=None,
    alias=[('web', 'allow-pull')]
)
Line 55: Line 126:
When loading options, both underscores and hyphens will be simply discarded. This implementation will allow us renaming options in the .hgrc file without any restrictions and/or backward compatibility issues. Note: we need to keep the old name as the original section/key configitem.
Line 57: Line 128:
=== Proposal: use {{{-}}} or {{{_}}} in config examples === === Proposal for sections: central config declaration ===
Line 59: Line 130:
While major options can be written in only one word, we should start using hyphens or underscores between words. Currently, config options do not needs to be declared in any special way. You just fetch a value in the code using `ui.config(section, name[, defaultvalue])`.
Line 61: Line 132:
People who think that '''backgroundcloseminfilecount''', '''graphnodetemplate''', '''mergemarkertemplate''' are actually readable should consider stop programming. On top of that, we have `contrib/check-config.py` that runs on the code in the Mercurial repository trying to catch:
Line 63: Line 134:
=== Problems ===  * inconsistent type used in config
 * undocumented config option
Line 65: Line 137:
Only options like '''post-<command>''' must not be mangled by the process of removing extraneous -_ characters. The proposal is to have a central declaration of all known configs options. That register would contains:
Line 67: Line 139:
What do to with them?  * section,
 * name,
 * default value,
 * documentation,
 * state: (deprecated, experimental, etc)

==== direct benefit ====

 * an issue devel warning on access to undefined option. Catching bug from minor typo (eg: `ui.config('path',…)` vs `ui.config('paths',…)`)

 * have declaration/documentation checks also runs for out of core extensions,

 * it becomes less error prone to update an option default value,

 * makes it easier for extensions to change default value,

 * makes it easier to discover existing config and section when adding a new options,

==== sub-proposal: config renaming ====

We could have official "config alias". For example, let's say we could rename `ui.clonebundleprefers` to `clonebundle.preference`, we declare the rename in the central repository and on access, if `clonebundle.preference` is undefined, the old name is checked instead (possibly with a transformation).

That would come really handy in regard with experimental option as we could rename them without breaking existing users.

Having such feature would also allow a large cleanup on the existing config options to merge some related section together and to split some minor options out of the `[ui]` section.

In addition, we could also, decide on one form standard for config option "name" (as describe in the earlier part of the document) and rename all existing one to match our pick.
Line 71: Line 169:
 * Implement code to allow extra -_ characters  * (./) write official naming guideline for options
 * (./) implement a central declaration
 * (./) implement alias support
 * {X} migrate documentation and default config to the central declaration
 * {X} devel warning for non-existing/inconsistent access
 * {X} official way for extensions to overwrite default
 * {X} implement config "forwarding"
 * {X} reorganize existing sections,

== SeeAlso ==

 * [[UIGuideline#config]
 
 * small patch to list all existing options: https://www.mercurial-scm.org/repo/users/marmoute/mercurial/rev/1696f686f616

Note:

This page is primarily intended for developers of Mercurial.

Configuration consolidation

Status: Project

Main proponents: DavidDemelier,Pierre-Yves David

/!\ This is a speculative project and does not represent any firm decisions on future behavior.

Make the .hgrc file more unified.

1. Goal

The goal of this project is to make a clear coding style regarding the .hgrc configuration options.

2. Detailed description

The current .hgrc configuration options is messed with many different styles:

  • anoption (~ 192 options, many are unreadable)
  • an_option (~ 8 options)
  • an-option (~ 7 options)

Having a unified style makes the code cleaner, better integrated.

In addition, having guideline for sections would be useful. In Mercurial core + bundle extension we have about 300 configuration option. They are spread in the following sections:

     34 ui
     28 convert
     27 experimental
     21 web
     20 bugzilla
     19 lists
     13 notify
     10 format
     10 devel
      9 values
      9 profiling
      7 server
      6 smtp
      5 worker
      5 patchbomb
      5 http_proxy
      4 progress
      4 mq
      3 pager
      3 histedit
      3 factotum
      3 eol
      3 email
      2 transplant
      2 share
      2 phases
      2 paths
      2 patch
      2 merge
      2 hostsecurity
      2 gpg
      2 fsmonitor
      2 color
      2 chgserver
      2 bundle
      2 blackbox
      2 acl
      1 win32text
      1 win32mbcs
      1 shelve
      1 perf
      1 keywordset
      1 hook
      1 hgk
      1 fakepatchtime
      1 fakedirstatewritetime
      1 debug
      1 cmdserver
      1 censor
      1 bookmarks
      1 automv

There are *many* options is the [ui] section and many section with version few config. Gathering related options in the same config section have multiple advantages. The main one is that it gather the related option in the documentation improving discoverability. For the same reason, having too many options is the [ui] is drowning the important ones in the help of more minor ones.

2.0.1. Proposal: use - in config examples

While major options can be written in only one word, we should start using hyphens between words.

Example:

[web]
allow-pull = foo
allow-push = bar

The actual config looks like this:

[web]
allowpull = foo
allow_push = bar # yes, for real

[progress]
assume-tty = yes

[worker]
backgroundcloseminfilecount = 12

Names like backgroundcloseminfilecount, graphnodetemplate, mergemarkertemplate are actually not readable by humans.

Using the implemented alias support, we can start renaming options to the new convention without any breakage.

coreconfigitem('web', 'allowpull',
    default=None,
    alias=[('web', 'allow-pull')]
)

Note: we need to keep the old name as the original section/key configitem.

2.1. Proposal for sections: central config declaration

Currently, config options do not needs to be declared in any special way. You just fetch a value in the code using ui.config(section, name[, defaultvalue]).

On top of that, we have contrib/check-config.py that runs on the code in the Mercurial repository trying to catch:

  • inconsistent type used in config
  • undocumented config option

The proposal is to have a central declaration of all known configs options. That register would contains:

  • section,
  • name,
  • default value,
  • documentation,
  • state: (deprecated, experimental, etc)

2.1.1. direct benefit

  • an issue devel warning on access to undefined option. Catching bug from minor typo (eg: ui.config('path',…) vs ui.config('paths',…))

  • have declaration/documentation checks also runs for out of core extensions,
  • it becomes less error prone to update an option default value,
  • makes it easier for extensions to change default value,
  • makes it easier to discover existing config and section when adding a new options,

2.1.2. sub-proposal: config renaming

We could have official "config alias". For example, let's say we could rename ui.clonebundleprefers to clonebundle.preference, we declare the rename in the central repository and on access, if clonebundle.preference is undefined, the old name is checked instead (possibly with a transformation).

That would come really handy in regard with experimental option as we could rename them without breaking existing users.

Having such feature would also allow a large cleanup on the existing config options to merge some related section together and to split some minor options out of the [ui] section.

In addition, we could also, decide on one form standard for config option "name" (as describe in the earlier part of the document) and rename all existing one to match our pick.

3. Roadmap

  • (./) write official naming guideline for options

  • (./) implement a central declaration

  • (./) implement alias support

  • {X} migrate documentation and default config to the central declaration

  • {X} devel warning for non-existing/inconsistent access

  • {X} official way for extensions to overwrite default

  • {X} implement config "forwarding"

  • {X} reorganize existing sections,

4. SeeAlso


CategoryDeveloper CategoryNewFeatures

ConfigConsolidationPlan (last edited 2018-03-28 10:44:39 by AntonShestakov)