Initial revision

1 files changed, 138 insertions, 0 deletions

diff --git a/Util/zsh-development-guide b/Util/zsh-development-guide
new file mode 100644
index 000000000..d574d8af0
--- /dev/null
+++ b/Util/zsh-development-guide
@@ -0,0 +1,138 @@
+------------------------------
+GUIDELINES FOR ZSH DEVELOPMENT
+------------------------------
+
+Zsh is currently developed and maintained by the Zsh Development Group.
+This development takes place by mailing list.  Check the META-FAQ for the
+various zsh mailing lists and how to subscribe to them.  The development
+is very open and anyone is welcomed and encouraged to join and contribute.
+Because zsh is a very large package whose development can sometimes
+be very rapid, I kindly ask that people observe a few guidelines when
+contributing patches and feedback to the mailing list.  These guidelines
+are very simple and hopefully should make for a more orderly development
+of zsh.
+
+Patches
+-------
+
+* Send all patches to the mailing list rather than directly to me.
+
+* Send only context diffs "diff -c oldfile newfile".  They are much
+  easier to read and understand while also allowing the patch program
+  to patch more intelligently.  Please make sure the filenames in
+  the diff header are relative to the top-level directory of the zsh
+  distribution; for example, it should say "Src/init.c" rather than
+  "init.c" or "zsh/Src/init.c".
+
+* Please put only one bug fix or feature enhancement in a single patch and
+  only one patch per mail message.  This helps me to multiplex the many
+  (possibly conflicting) patches that I receive for zsh.  You shouldn't
+  needlessly split patches, but send them in the smallest LOGICAL unit.
+
+* If a patch depends on other patches, then please say so.  Also please
+  mention what version of zsh this patch is for.
+
+* Please test your patch and make sure it applies cleanly. It takes
+  considerably more time to manually merge a patch into the baseline code.
+
+* There is now a zsh patch archive.  To have your patches appear in the
+  archive, send them to the mailing list with a Subject: line starting
+  with "PATCH:".
+
+C coding style
+--------------
+
+* The primary language is ANSI C as defined by the 1989 standard, but the
+  code should always be compatible with late K&R era compilers ("The C
+  Programming Language" 1st edition, plus "void" and "enum").  There are
+  many hacks to avoid the need to actually restrict the code to K&R C --
+  check out the configure tests -- but always bear the compatibility
+  requirements in mind.  In particular, preprocessing directives must
+  have the "#" unindented, and string pasting is not available.
+
+* Conversely, there are preprocessor macros to provide safe access to some
+  language features not present in pure ANSI C, such as variable-length
+  arrays.  Always use the macros if you want to use these facilities.
+
+* Avoid writing code that generates warnings under gcc with the default
+  options set by the configure script.  For example, write
+  "if ((foo = bar))" rather than "if (foo = bar)".
+
+* Please try not using lines longer than 79 characters.
+
+* The indent/brace style is Kernighan and Ritchie with 4 characters
+  indentations (with leading tab characters replacing sequences of
+  8 spaces).  This means that the opening brace is the last character
+  in the line of the if/while/for/do statement and the closing brace
+  has its own line:
+
+      if (foo) {
+	  do that
+      }
+
+* Put only one simple statement on a line.  The body of an if/while/for/do
+  statement has its own line with 4 characters indentation even if there
+  are no braces.
+
+* Do not use space between the function name and the opening parenthesis.
+  Use space after if/for/while.  Use space after type casts.
+
+* Do not use (unsigned char) casts since some compilers do not handle
+  them properly.  Use the provided STOUC(X) macro instead.
+
+* If you use emacs 19.30 or newer you can put the following line to your
+  ~/.emacs file to make these formatting rules the default:
+
+    (add-hook 'c-mode-common-hook (function (lambda () (c-set-style "BSD"))))
+
+* Function declarations must look like this:
+
+  /**/
+  int
+  foo(char *s, char **p)
+  {
+      function body
+  }
+
+  There must be an empty line, a line with "/**/", a line with the
+  type of the function, and finally the name of the function with typed
+  arguments.  These lines must not be indented.  The script generating
+  function prototypes and the ansi2knr program depend on this format.
+  If the function is not used outside the file it is defined in, it
+  should be declared "static"; this keyword goes on the type line,
+  before the return type.
+
+* Global variable declarations must similarly be preceded by a
+  line containing only "/**/", for the prototype generation script.
+  The declaration itself should be all on one line (except for multi-line
+  initialisers).
+
+* Leave a blank line between the declarations and statements in a compound
+  statement, if both are present.  Use blank lines elsewhere to separate
+  groups of statements in the interests of clarity.  There should never
+  be two consecutive blank lines.
+
+Documentation
+-------------
+
+* Edit only the .yo files.  All other formats (man pages, TeXinfo, HTML,
+  etc.) are automatically generated from the yodl source.
+
+* Always use the correct markup.  em() is used for emphasis, and bf()
+  for citations.  tt() marks text that is literal input to or output
+  from the shell.  var() marks metasyntactic variables.
+
+* In addition to appropriate markup, always use quotes (`') where
+  appropriate.  Specifically, use quotes to mark text that is not a part
+  of the actual text of the documentation (i.e., that it is being quoted).
+  In principle, all combinations of quotes and markup are possible,
+  because the purposes of the two devices are completely orthogonal.
+  For example,
+
+      Type `tt(xyzzy)' to let zsh know you have played tt(advent).
+      Saying `plugh' aloud doesn't have much effect, however.
+
+  In this case, "zsh" is normal text (a name), "advent" is a command name
+  ocurring in the main text, "plugh" is a normal word that is being quoted
+  (it's the user that says `plugh', not the documentation), and "xyzzy"
+  is some text to be typed literally that is being quoted.