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