Error message conventions

I have tried to describe the changes I made to the error messages I have
done for issue 897 so far. The patch below is an addition for the HACKING file,
but that is beside the point for now. It is not a patch submission yet.
Rather I would like to discuss if you agree with what it says. I'm interested in
additions, but also incorrectness or just disagreement.

The patch below tries to describe the conventions I try to adhere to when
changing error messages for issue 897; it can also be found at
http://encorps.dnsalias.com/svn-public/patches/HACKING.patch.

Here is the not-a-patch-submission-yet:
Index: HACKING
===================================================================
--- HACKING (revision 7765)
+++ HACKING (working copy)
@@ -19,6 +19,7 @@
    * Secure coding guidelines
    * Document everything
    * Using page breaks
+ * Error message conventions
    * Other conventions
    * APR pool usage conventions
    * APR status codes
@@ -371,6 +372,44 @@
 
 
 
+Error message conventions
+=========================
+
+For error messages the following conventions apply:
+
+ * Provide specific error messages only when there is information
+ to add to the general error message found in
+ subversion/include/svn_error_codes.h
+
+ * Messages start with a capital letter.
+
+ * Keep messages below 70 characters.
+
+ * Don't end the error message with a '.'.
+
+ * Don't include newline characters in error messages.
+
+ * Quoting information is done using single quotes ('some info').
+
+ * Don't include the name of the function where the error occurs
+ in the error message. If subversion is compiled using the
+ '--enable-maintainer-mode' configure-flag, if will provide this
+ information by itself.
+
+ * When including path or filenames in the error string, be sure
+ to quote them. (i.e. "Can't find '/path/to/repos/userfile'")
+
+ * If you want to add an explanation to the error, report the error,
+ followed by a colon and the explanation like this:
+ "Invalid " SVN_PROP_EXTERNALS " property on '%s': "
+ "target involves '.' or '..'"
+
+ * Suggestions or other additions can be added after a semi-colon,
+ like this:
+ "Can't write to '%s': object of same name already exists; remove "
+ "before retrying"
+
+
 Other conventions
 =================
 

-- 
GMX Weihnachts-Special: Seychellen-Traumreise zu gewinnen!
Rentier entlaufen. Finden Sie Rudolph! Als Belohnung winken
tolle Preise. http://www.gmx.net/de/cgi/specialmail/
+++ GMX - die erste Adresse für Mail, Message, More! +++
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org