We may want to say something about command line option names in the
new section as well, but for now, let's make sure everybody is clear
on how to structure and name their configuration variables.
The text for the rules are partly taken from the log message of
Jonathan's 6b3020a2 (add: introduce add.ignoreerrors synonym for
add.ignore-errors, 2010-12-01).
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
---
Documentation/CodingGuidelines | 25 +++++++++++++++++++++++++
1 file changed, 25 insertions(+)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 894546d..8fbac15 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -413,6 +413,31 @@ 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), but also
+ large fixed set defined by the system that can grow over time
+ (e.g. what kind of common whitespace problems to notice). Use
+ subsection names or variable values, like existing variables
+ branch.<name>.description and core.whitespace do, instead.
+
+
Writing Documentation:
Most (if not all) of the documentation pages are written in the
--
2.3.0-rc2-149-gdd42ee9
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html