Provide some linguistic guidance for the documentation.
This will hopefully avoid questions over which spelling and grammar should be used. Translators are of course free to create localizations for specific English dialects. Signed-off-by: Marc Branchaud <marcnarc@xiplink.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Marc Branchaud committed
Aug 1, 2013 at 14:49 UTC
42e0fae98e592c296aa5726c9dfd41ef255d1299
2 files changed
+22
-1
Documentation/CodingGuidelines
+8
@@ -242,6 +242,14 @@ Writing Documentation:
242
processed into HTML and manpages (e.g. git.html and git.1 in the
243
same directory).
244
245
+ The documentation liberally mixes US and UK English (en_US/UK)
246
+ norms for spelling and grammar, which is somewhat unfortunate.
247
+ In an ideal world, it would have been better if it consistently
248
+ used only one and not the other, and we would have picked en_US
249
+ (if you wish to correct the English of some of the existing
250
+ documentation, please see the documentation-related advice in the
251
+ Documentation/SubmittingPatches file).
252
+
253
Every user-visible change should be reflected in the documentation.
254
The same general rule as for code applies -- imitate the existing
255
conventions. A few commented examples follow to provide reference
Documentation/SubmittingPatches
+14
-1
@@ -65,7 +65,20 @@ feature does not trigger when it shouldn't. Also make sure that the
65
test suite passes after your commit. Do not forget to update the
66
documentation to describe the updated behaviour.
67
68
-Oh, another thing. I am picky about whitespaces. Make sure your
68
+Speaking of the documentation, it is currently a liberal mixture of US
69
+and UK English norms for spelling and grammar, which is somewhat
70
+unfortunate. A huge patch that touches the files all over the place
71
+only to correct the inconsistency is not welcome, though. Potential
72
+clashes with other changes that can result from such a patch are not
73
+worth it. We prefer to gradually reconcile the inconsistencies in
74
+favor of US English, with small and easily digestible patches, as a
75
+side effect of doing some other real work in the vicinity (e.g.
76
+rewriting a paragraph for clarity, while turning en_UK spelling to
77
+en_US). Obvious typographical fixes are much more welcomed ("teh ->
78
+"the"), preferably submitted as independent patches separate from
79
+other documentation changes.
80
+
81
+Oh, another thing. We are picky about whitespaces. Make sure your
82
changes do not trigger errors with the sample pre-commit hook shipped
83
in templates/hooks--pre-commit. To help ensure this does not happen,
84
run git diff --check on your changes before you commit.