From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 11 Feb 2015 21:37:42 +0000 (-0800)
Subject: Merge branch 'jc/coding-guidelines'
X-Git-Tag: v2.4.0-rc0~142
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/fcae987e946ff25e055b7cc5b5b9801d682a7baf?ds=inline;hp=-c

Merge branch 'jc/coding-guidelines'

* jc/coding-guidelines:
CodingGuidelines: clarify C #include rules
---

fcae987e946ff25e055b7cc5b5b9801d682a7baf
diff --combined Documentation/CodingGuidelines
index 894546dd75,ae8b42f3be..578d07c034
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@@ -328,9 -328,14 +328,14 @@@ For C programs
  
   - When you come up with an API, document it.
  
-  - The first #include in C files, except in platform specific
-    compat/ implementations, should be git-compat-util.h or another
-    header file that includes it, such as cache.h or builtin.h.
+  - The first #include in C files, except in platform specific compat/
+    implementations, must be either "git-compat-util.h", "cache.h" or
+    "builtin.h".  You do not have to include more than one of these.
+ 
+  - A C file must directly include the header files that declare the
+    functions and the types it uses, except for the functions and types
+    that are made available to it by including one of the header files
+    it must include by the previous rule.
  
   - If you are planning a new command, consider writing it in shell
     or perl first, so that changes in semantics can be easily
@@@ -404,15 -409,6 +409,15 @@@ For Python scripts
     documentation for version 2.6 does not mention this prefix, it has
     been supported since version 2.6.0.
  
 +Error Messages
 +
 + - Do not end error messages with a full stop.
 +
 + - Do not capitalize ("unable to open %s", not "Unable to open %s")
 +
 + - Say what the error is first ("cannot open %s", not "%s: cannot open")
 +
 +
  Writing Documentation:
  
   Most (if not all) of the documentation pages are written in the