From 42e0fae98e592c296aa5726c9dfd41ef255d1299 Mon Sep 17 00:00:00 2001 From: Marc Branchaud Date: Thu, 1 Aug 2013 14:49:54 -0400 Subject: [PATCH] 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 Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 8 ++++++++ Documentation/SubmittingPatches | 15 ++++++++++++++- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 559d5f9ebf..e5ca3b75d3 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -242,6 +242,14 @@ Writing Documentation: processed into HTML and manpages (e.g. git.html and git.1 in the same directory). + The documentation liberally mixes US and UK English (en_US/UK) + norms for spelling and grammar, which is somewhat unfortunate. + In an ideal world, it would have been better if it consistently + used only one and not the other, and we would have picked en_US + (if you wish to correct the English of some of the existing + documentation, please see the documentation-related advice in the + Documentation/SubmittingPatches file). + Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions. A few commented examples follow to provide reference diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d0a4733e45..705557689d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -65,7 +65,20 @@ feature does not trigger when it shouldn't. Also make sure that the test suite passes after your commit. Do not forget to update the documentation to describe the updated behaviour. -Oh, another thing. I am picky about whitespaces. Make sure your +Speaking of the documentation, it is currently a liberal mixture of US +and UK English norms for spelling and grammar, which is somewhat +unfortunate. A huge patch that touches the files all over the place +only to correct the inconsistency is not welcome, though. Potential +clashes with other changes that can result from such a patch are not +worth it. We prefer to gradually reconcile the inconsistencies in +favor of US English, with small and easily digestible patches, as a +side effect of doing some other real work in the vicinity (e.g. +rewriting a paragraph for clarity, while turning en_UK spelling to +en_US). Obvious typographical fixes are much more welcomed ("teh -> +"the"), preferably submitted as independent patches separate from +other documentation changes. + +Oh, another thing. We are picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped in templates/hooks--pre-commit. To help ensure this does not happen, run git diff --check on your changes before you commit. -- 2.11.4.GIT