]>
Commit | Line | Data |
---|---|---|
5b25658f | 1 | This text describes contribution procedures to systemtap. Please read |
bab2d8d0 | 2 | and understand them before jumping in. Discussions take place on |
5b25658f FCE |
3 | the <systemtap@sources.redhat.com> mailing list. |
4 | ||
5 | - general | |
6 | ||
7 | Submissions should be in an easy-to-read diff/patch form, unless | |
8 | this is inappropriate due to size, relevance, or fraction of novel | |
377f3fa9 JS |
9 | content. They should be accompanied by an explanation. The |
10 | relevant test suites should be run before and after your changes, | |
11 | and regressions avoided, explained, or corrected. | |
5b25658f | 12 | |
3b312701 | 13 | Established contributors may be considered for direct GIT write |
5b25658f FCE |
14 | access. Other contributors should simply pack up the goods into a |
15 | plain text email message to the mailing list. | |
16 | ||
17 | - obvious changes | |
18 | ||
19 | Trivial, obvious patches may be posted or committed without other | |
20 | formalities. | |
21 | ||
22 | - copyright | |
23 | ||
24 | You must designate the appropriate copyright holder for your | |
25 | contribution. If not already there, this name should be added by | |
26 | your patch to the copyright header in the affected files. The | |
27 | copyright holder is assumed to agree with the general licensing | |
28 | terms (GPLv2+). | |
29 | ||
30 | - coding style | |
31 | ||
32 | Abide by the general formatting of the code you are modifying. The | |
377f3fa9 JS |
33 | code base generally follows the GNU standards in usermode code and |
34 | the Linux kernel standards in runtime code. | |
5b25658f | 35 | |
377f3fa9 JS |
36 | - commit messages |
37 | ||
38 | In the git commit message, make the first line a brief (<=50 char) | |
39 | summary of the patch, and leave the second line blank. If you have | |
40 | trouble coming up with a concise summary, consider whether your | |
41 | patch might be better broken into smaller commits. | |
42 | ||
43 | For trivial changes, the summary alone may be sufficient, but most | |
44 | commits should include a paragraph or two giving more details about | |
45 | what the change is and why it is needed. Extra information like | |
46 | bugzilla numbers and mailing-list discussion links are appreciated | |
47 | as a supplement, but they are not a replacement for a real | |
48 | description. | |
ee6ce753 | 49 | |
5b25658f FCE |
50 | - test suites |
51 | ||
52 | As far as practicable, changes should be accompanied by test cases | |
1dca31ba | 53 | to prevent future regressions. Tests should be run on at least |
814bc89d FCE |
54 | x86, and ideally also on some 64-bit platform. The test suite is |
55 | located under /src/testsuite and is based on dejagnu. "make check" | |
56 | runs unprivileged tests only against an uninstalled build tree. | |
57 | "make installcheck" runs all tests against an installed tree. | |
5b25658f FCE |
58 | |
59 | Tests that don't require probe execution should go into new or | |
814bc89d FCE |
60 | modified files under the *{ok,ko} directories, which are scanned |
61 | by corresponding systemtap.pass1-4/*.exp files. The "ko" tests are | |
62 | for expected (deliberate) errors. | |
63 | ||
64 | Tests that execute probes (pass 5) should include their own .exp/.stp | |
65 | files under any other appropriate systemtap.* testsuite subdirectory. | |
5b25658f | 66 | |
dcf2fef8 JK |
67 | To run a particular test or set of tests, do: |
68 | cd testsuite | |
69 | make check RUNTESTFLAGS=testname.exp | |
70 | or | |
71 | make installcheck RUNTESTFLAGS=testname.exp | |
72 | To disambiguate among multiple tests with the same name, specify | |
73 | the directory as well -- for example: | |
74 | make installcheck RUNTESTFLAGS=systemtap.base/print.exp | |
75 | ||
5b25658f FCE |
76 | - translator |
77 | ||
78 | Translator changes can easily invalidate tapsets and user script | |
79 | code. One must tread carefully and run regression tests rigorously. | |
80 | Both positive and negative polarity (expect-pass / expect-fail) test | |
81 | cases may need to be written to assert a bug fix. Script language | |
d633e387 FCE |
82 | changes should be documented in the stap.1 man page and emphasized |
83 | in the NEWS file. | |
5b25658f FCE |
84 | |
85 | - tapsets | |
86 | ||
87 | Tapset script files should demonstrate effective economy, and avoid | |
88 | conflicts with user and other tapset code. | |
89 | ||
90 | It may be necessary to prefix symbols with the tapset name to ensure | |
dbbb2cec | 91 | systemtap-wide uniqueness. All "external interfaces" expected to be |
5b25658f | 92 | used by user scripts (or perhaps other tapsets) should be documented |
d633e387 FCE |
93 | in stapfuncs.5, stapprobes.5. Major or incompatible changes should |
94 | be mentioned in the NEWS file. | |
95 | ||
96 | Internal function, variable, probe identifiers should be prefixed | |
97 | with "_" for extra uniqueness, and not documented in the man pages. | |
5b25658f | 98 | |
a9a29deb FCE |
99 | Tapsets should come with a tests cases that provide good test coverage. |
100 | Every alias definition should be tested for pass-2 correctness. Every | |
101 | embedded-C routine should be tested for pass-4 buildability and ideally | |
102 | pass-5 correctness. The platforms/architectures against which the tapset | |
103 | was tested should be published, and ideally asserted by code. | |
104 | ||
105 | Embedded-C code should avoid making references to the runtime or | |
15f3a3ef FCE |
106 | other code possibly generated by the translator. Embedded-C code that |
107 | dereferences pointers should use deref() type functions to check each | |
108 | individual operation if there exists a possibility that the function may | |
109 | be called with invalid pointers or pointer chains. | |
5b25658f FCE |
110 | |
111 | - runtime | |
112 | ||
113 | Changes to the runtime can cause problems on different architectures | |
114 | or kernel versions. Luckily, many code mistakes show up easily in | |
34f6a71c | 115 | the pass-4 tests. |
5b25658f FCE |
116 | |
117 | - meta | |
118 | ||
119 | Proposed changes to these guidelines should be discussed on the | |
120 | mailing list. |