]>
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 |
306dd4f8 | 3 | the <systemtap@sourceware.org> mailing list. |
5b25658f FCE |
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 | ||
7d386339 FCE |
17 | It is not necessary to include machine-generated files like |
18 | autoconf*, sample-script indexes, etc. in patches posted for | |
19 | review. | |
20 | ||
5b25658f FCE |
21 | - obvious changes |
22 | ||
23 | Trivial, obvious patches may be posted or committed without other | |
24 | formalities. | |
25 | ||
26 | - copyright | |
27 | ||
28 | You must designate the appropriate copyright holder for your | |
29 | contribution. If not already there, this name should be added by | |
30 | your patch to the copyright header in the affected files. The | |
31 | copyright holder is assumed to agree with the general licensing | |
32 | terms (GPLv2+). | |
33 | ||
34 | - coding style | |
35 | ||
36 | Abide by the general formatting of the code you are modifying. The | |
377f3fa9 JS |
37 | code base generally follows the GNU standards in usermode code and |
38 | the Linux kernel standards in runtime code. | |
5b25658f | 39 | |
377f3fa9 JS |
40 | - commit messages |
41 | ||
42 | In the git commit message, make the first line a brief (<=50 char) | |
43 | summary of the patch, and leave the second line blank. If you have | |
44 | trouble coming up with a concise summary, consider whether your | |
45 | patch might be better broken into smaller commits. | |
46 | ||
47 | For trivial changes, the summary alone may be sufficient, but most | |
48 | commits should include a paragraph or two giving more details about | |
49 | what the change is and why it is needed. Extra information like | |
50 | bugzilla numbers and mailing-list discussion links are appreciated | |
51 | as a supplement, but they are not a replacement for a real | |
52 | description. | |
ee6ce753 | 53 | |
5b25658f FCE |
54 | - test suites |
55 | ||
56 | As far as practicable, changes should be accompanied by test cases | |
1dca31ba | 57 | to prevent future regressions. Tests should be run on at least |
814bc89d FCE |
58 | x86, and ideally also on some 64-bit platform. The test suite is |
59 | located under /src/testsuite and is based on dejagnu. "make check" | |
60 | runs unprivileged tests only against an uninstalled build tree. | |
61 | "make installcheck" runs all tests against an installed tree. | |
5b25658f FCE |
62 | |
63 | Tests that don't require probe execution should go into new or | |
814bc89d FCE |
64 | modified files under the *{ok,ko} directories, which are scanned |
65 | by corresponding systemtap.pass1-4/*.exp files. The "ko" tests are | |
66 | for expected (deliberate) errors. | |
67 | ||
68 | Tests that execute probes (pass 5) should include their own .exp/.stp | |
69 | files under any other appropriate systemtap.* testsuite subdirectory. | |
5b25658f | 70 | |
dcf2fef8 JK |
71 | To run a particular test or set of tests, do: |
72 | cd testsuite | |
73 | make check RUNTESTFLAGS=testname.exp | |
74 | or | |
75 | make installcheck RUNTESTFLAGS=testname.exp | |
76 | To disambiguate among multiple tests with the same name, specify | |
77 | the directory as well -- for example: | |
78 | make installcheck RUNTESTFLAGS=systemtap.base/print.exp | |
79 | ||
5b25658f FCE |
80 | - translator |
81 | ||
82 | Translator changes can easily invalidate tapsets and user script | |
83 | code. One must tread carefully and run regression tests rigorously. | |
84 | Both positive and negative polarity (expect-pass / expect-fail) test | |
85 | cases may need to be written to assert a bug fix. Script language | |
d633e387 FCE |
86 | changes should be documented in the stap.1 man page and emphasized |
87 | in the NEWS file. | |
5b25658f FCE |
88 | |
89 | - tapsets | |
90 | ||
91 | Tapset script files should demonstrate effective economy, and avoid | |
92 | conflicts with user and other tapset code. | |
93 | ||
94 | It may be necessary to prefix symbols with the tapset name to ensure | |
dbbb2cec | 95 | systemtap-wide uniqueness. All "external interfaces" expected to be |
5b25658f | 96 | used by user scripts (or perhaps other tapsets) should be documented |
5fae6ccb SM |
97 | -- either in stapprobes.3stap if they are built into the language or |
98 | otherwise somehow essential; or in kernel-doc style comments if they | |
99 | are defined in a tapset (see almost any existing tapset for an | |
100 | example of how this is done); any new tapset should be mentioned in | |
101 | doc/SystemTap_Tapset_Reference/tapsets.tmpl. Major or incompatible | |
102 | changes should be mentioned in the NEWS file; see also the | |
103 | deprecation section below. | |
d633e387 FCE |
104 | |
105 | Internal function, variable, probe identifiers should be prefixed | |
106 | with "_" for extra uniqueness, and not documented in the man pages. | |
5b25658f | 107 | |
23928772 FCE |
108 | Tapsets should come with a tests cases that provide good test |
109 | coverage. Every alias definition should be tested for pass-2 | |
110 | correctness. Every embedded-C routine should be tested for pass-4 | |
111 | buildability. As they are a security hazard, every tapset | |
112 | embedded-C routine should be pass-5 stress-tested for response to | |
113 | erroneous inputs. This applies doubly to /* unprivileged */ ones. | |
114 | The platforms/architectures against which the tapset was tested | |
115 | should be published, and ideally asserted by code. | |
a9a29deb FCE |
116 | |
117 | Embedded-C code should avoid making references to the runtime or | |
15f3a3ef FCE |
118 | other code possibly generated by the translator. Embedded-C code that |
119 | dereferences pointers should use deref() type functions to check each | |
120 | individual operation if there exists a possibility that the function may | |
121 | be called with invalid pointers or pointer chains. | |
5b25658f | 122 | |
bdb3681a FCE |
123 | - deprecation |
124 | ||
125 | Try to remain compatible with existing valid scripts, with respect | |
126 | to changes in the script language or the tapset. Where this is not | |
874e4125 | 127 | practicable, preserve the old functionality using the %( systemtap_v %) |
bdb3681a | 128 | preprocessor conditional in the tapset and systemtap_session.compatible |
874e4125 FCE |
129 | in the translator. If needed, after several major releases, |
130 | deprecated functionality may be dropped outright. Note both pending | |
131 | and final deprecation in NEWS and the permanent DEPRECATION section | |
132 | in stap.1. The intent is to protect old scripts for a year or longer. | |
bdb3681a FCE |
133 | |
134 | Tapset functions to be deprecated should be kept for at least one | |
135 | major release. For example, if we're in development between versions | |
b352f4b0 | 136 | 1.2 and 1.3, wrap to-be-deprecated tapset functions or probes in |
874e4125 | 137 | %( systemtap_v <= "1.3" %? function foo() {} %) |
bdb3681a FCE |
138 | so as to preserve the tapset function during the life of the 1.3 release. |
139 | ||
140 | Script language changes that cause earlier valid scripts to become | |
141 | invalid should be opt-in (requiring --compatible=NEWVERSION) for at | |
142 | least one major release before becoming default. For example, test | |
143 | strverscmp(s.compatible.c_str(), "1.4") >= 0 | |
144 | in the 1.3 release sources in order to activate the change. | |
145 | ||
5b25658f FCE |
146 | - runtime |
147 | ||
148 | Changes to the runtime can cause problems on different architectures | |
149 | or kernel versions. Luckily, many code mistakes show up easily in | |
34f6a71c | 150 | the pass-4 tests. |
5b25658f | 151 | |
efbfa04e FCE |
152 | - i18n |
153 | ||
154 | We use the zanata [1] system for managing translations of runtime | |
155 | strings. If interested, create yourself a zanata account, and help | |
156 | translate online! In addition, you can ship systemtap sources | |
157 | to/from zanata by installing the zanata-cli and getting a | |
977e0c06 FCE |
158 | $HOME/.config/zanata.ini file, thereafter following the advice [2][3] |
159 | of "make update-po" (invoked from the top of the build tree). | |
efbfa04e FCE |
160 | |
161 | [1] https://translate.zanata.org/zanata/iteration/view/systemtap/master | |
162 | [2] http://zanata.org/help/cli/cli-push | |
163 | [3] http://zanata.org/help/cli/cli-pull | |
164 | ||
5b25658f FCE |
165 | - meta |
166 | ||
167 | Proposed changes to these guidelines should be discussed on the | |
168 | mailing list. | |
ca4c620d FCE |
169 | |
170 | - git basics | |
171 | ||
306dd4f8 FCE |
172 | git clone ssh://sourceware.org/git/systemtap.git |
173 | # OR: use git://sourceware.org/git/systemtap.git then add to .git/config: | |
c31177fb | 174 | # [remote "origin"] |
306dd4f8 | 175 | # pushurl=ssh://sourceware.org/git/systemtap.git |
ca4c620d | 176 | # build ; hack hack hack; test |
019fd25d FCE |
177 | git add FILE1 FILE2 # enumerate all modified or new files |
178 | git status # to confirm that needed local changes are "staged" | |
ca4c620d | 179 | git commit # to your local repository, add nice commit message |
019fd25d | 180 | git show # to check that the last commit included all changes |
ca4c620d FCE |
181 | git pull # to make sure your copy is up to date & merged |
182 | # last minute rebuild; retest | |
183 | git rebase origin/master # clean git commit of merge history | |
184 | git diff origin/master # final visual check | |
8e553dbf FCE |
185 | |
186 | git push # to the central one, if you have access | |
187 | OR git format-patch -s origin/master.. | |
188 | then email the resulting files to the mailing list |