Debian Codegraph @

HACKING

raw
1 This text describes contribution procedures to systemtap. Please read
2 and understand them before jumping in. Discussions take place on
3 the <[email protected]> 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
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.
12
13 Established contributors may be considered for direct GIT write
14 access. Other contributors should simply pack up the goods into a
15 plain text email message to the mailing list.
16
17 It is not necessary to include machine-generated files like
18 autoconf*, sample-script indexes, etc. in patches posted for
19 review.
20
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
37 code base generally follows the GNU standards in usermode code and
38 the Linux kernel standards in runtime code.
39
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.
53
54 - test suites
55
56 As far as practicable, changes should be accompanied by test cases
57 to prevent future regressions. Tests should be run on at least
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.
62
63 Tests that don't require probe execution should go into new or
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.
70
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
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
86 changes should be documented in the stap.1 man page and emphasized
87 in the NEWS file.
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
95 systemtap-wide uniqueness. All "external interfaces" expected to be
96 used by user scripts (or perhaps other tapsets) should be documented
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.
104
105 Internal function, variable, probe identifiers should be prefixed
106 with "_" for extra uniqueness, and not documented in the man pages.
107
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.
116
117 Embedded-C code should avoid making references to the runtime or
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.
122
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
127 practicable, preserve the old functionality using the %( systemtap_v %)
128 preprocessor conditional in the tapset and systemtap_session.compatible
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.
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
136 1.2 and 1.3, wrap to-be-deprecated tapset functions or probes in
137 %( systemtap_v <= "1.3" %? function foo() {} %)
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
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
150 the pass-4 tests.
151
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
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).
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
165 - meta
166
167 Proposed changes to these guidelines should be discussed on the
168 mailing list.
169
170 - git basics
171
172 git clone ssh://sourceware.org/git/systemtap.git
173 # OR: use git://sourceware.org/git/systemtap.git then add to .git/config:
174 # [remote "origin"]
175 # pushurl=ssh://sourceware.org/git/systemtap.git
176 # build ; hack hack hack; test
177 git add FILE1 FILE2 # enumerate all modified or new files
178 git status # to confirm that needed local changes are "staged"
179 git commit # to your local repository, add nice commit message
180 git show # to check that the last commit included all changes
181 git pull # to make sure your copy is up to date & merged
182 # last minute rebuild; retest
183 git rebase origin/main # clean git commit of merge history
184 git diff origin/main # final visual check
185
186 git push # to the central one, if you have access
187 OR git format-patch -s origin/main..
188 then email the resulting files to the mailing list