Mercurial > hg > index.cgi

comparison 00README.txt @ 322:69adaab94ffd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add notes about coding style and submission guidelines. As became clear from recent conversation, matching submitted code to the format of the existing code is not an obvious thing to do. (It should be but apparently it just doesn't occur to people.) Some description of the coding style is now present in the README. Additionally, submission guidelines have also been added to make it clear that patches (diffs) are the preferred means of providing code changes.
author William Astle <lost@l-w.ca>
date Mon, 03 Mar 2014 21:54:12 -0700
parents 03f425c6c39c
children 48b1cc3991d8
comparison
equal deleted inserted replaced
321:d4ac484d0ec6 322:69adaab94ffd
11 If you feel adventurous, you can also run the test suite by running "make 11 If you feel adventurous, you can also run the test suite by running "make
12 test". However, be warned that it is likely not going to work unless you are 12 test". However, be warned that it is likely not going to work unless you are
13 running on a fairly standard unix system with perl in /usr/bin/perl. 13 running on a fairly standard unix system with perl in /usr/bin/perl.
14 14
15 See docs/ for additional information. 15 See docs/ for additional information.
16
17 CONTRIBUTING
18 ============
19
20 If you wish to contribute patches or code to lwtools, please keep the
21 following in mind.
22
23 Style
24 -----
25
26 The code formatting style must match the rest of the lwtools code. Code
27 submitted in the "1TBS" will be rejected out of hand. Attempts to convince
28 me to change my mind on this point will be routed to /dev/null at best and
29 likely met with extreme rudeness.
30
31 C code should be formatted as follows:
32
33 * All indentation uses a single TAB character for each step. That is a HARD
34 tab, not a series of spaces. TABs are assumed to be 4 characters though
35 that will largely impact only lining up comments and tabular code. If the
36 actual formatting of the code is critical, spaces may be used for that
37 formatting but the actual initial indentation of the lines MUST use TAB
38 characters.
39 * The opening brace for a block appears on the line below the control
40 structure that introduces it. It appears lined up with the preceding line
41 and nothing else appears on the same line.
42 * Closing braces appear on a line by themselves ordinarily. The exception is
43 the "while" keyword in a "do-while" statement appears on the same line as
44 the closing brace for the block.
45 * Case labels are lined up with the enclosing block (one level back from the
46 code of the block). The same guideline applies for ordinarily labels.
47 * No spaces surround parentheses, brackets, or the dot operator. No space
48 precedes a comma but a space should follow it. Other operators should
49 usually be surrounded by spaces. A space should separate a keyword from
50 any surrounding except for sizeof() which should be written like a
51 function call. There is no space between a function name and the start of
52 its parameter list.
53
54 In general, study the existing source formatting and copy the style. This is
55 what you should do anyway and the above should not be required.
56
57 For code accepted to the contrib/ hierarchy, application of the above coding
58 style may be less strict.
59
60 Submitting
61 ----------
62
63 When submitting code to lwtools, it should be submitted as a patch file (hg
64 diff or diff -u). DO NOT submit entire source files. Remember, others may be
65 working on changes, too, and your complete source files are difficult to
66 merge with such situations. By submitting complete source files, you are
67 making far more work for the maintainer and it is generally considered rude.
68
69 Always specify what version of the source you based your patch on. If
70 possible, work off the default branch in the mercurial repository. At the
71 very least, make sure you are working with the most recent release.
72
73 It is also worth checking with the maintainer before submitting a patch.
74 There may be some reason why your pet feature is not present in the official
75 release.
76
77 Finally, be prepared to receive a list of deficiencies or requests for
78 improvements or clarification of why or how you did something.