summaryrefslogtreecommitdiff
path: root/Documentation/CodingGuidelines
diff options
context:
space:
mode:
authorLibravatar Junio C Hamano <gitster@pobox.com>2015-02-22 12:28:31 -0800
committerLibravatar Junio C Hamano <gitster@pobox.com>2015-02-22 12:28:31 -0800
commit9a9c1f1fdfb4e8bb253bfa27311e8a8ad82c8859 (patch)
treed46d48f1f8b72f2a7d11683d574acf763caad29b /Documentation/CodingGuidelines
parentMerge branch 'es/squelch-openssl-warnings-on-macosx' (diff)
parentCodingGuidelines: describe naming rules for configuration variables (diff)
downloadtgif-9a9c1f1fdfb4e8bb253bfa27311e8a8ad82c8859.tar.xz
Merge branch 'jc/conf-var-doc'
Longstanding configuration variable naming rules has been added to the documentation. * jc/conf-var-doc: CodingGuidelines: describe naming rules for configuration variables config.txt: mark deprecated variables more prominently config.txt: clarify that add.ignore-errors is deprecated
Diffstat (limited to 'Documentation/CodingGuidelines')
-rw-r--r--Documentation/CodingGuidelines23
1 files changed, 23 insertions, 0 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 49089de5c0..7636199fe8 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -418,6 +418,29 @@ Error Messages
- Say what the error is first ("cannot open %s", not "%s: cannot open")
+Externally Visible Names
+
+ - For configuration variable names, follow the existing convention:
+
+ . The section name indicates the affected subsystem.
+
+ . The subsection name, if any, indicates which of an unbounded set
+ of things to set the value for.
+
+ . The variable name describes the effect of tweaking this knob.
+
+ The section and variable names that consist of multiple words are
+ formed by concatenating the words without punctuations (e.g. `-`),
+ and are broken using bumpyCaps in documentation as a hint to the
+ reader.
+
+ When choosing the variable namespace, do not use variable name for
+ specifying possibly unbounded set of things, most notably anything
+ an end user can freely come up with (e.g. branch names). Instead,
+ use subsection names or variable values, like the existing variable
+ branch.<name>.description does.
+
+
Writing Documentation:
Most (if not all) of the documentation pages are written in the