------------------------------ 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.