This text describes contribution procedures to systemtap. Please read and understand them before jumping in. Discussions take place on the mailing list. - general Submissions should be in an easy-to-read diff/patch form, unless this is inappropriate due to size, relevance, or fraction of novel content. They should be accompanied by an explanation. The relevant test suites should be run before and after your changes, and regressions avoided, explained, or corrected. Established contributors may be considered for direct GIT write access. Other contributors should simply pack up the goods into a plain text email message to the mailing list. - obvious changes Trivial, obvious patches may be posted or committed without other formalities. - copyright You must designate the appropriate copyright holder for your contribution. If not already there, this name should be added by your patch to the copyright header in the affected files. The copyright holder is assumed to agree with the general licensing terms (GPLv2+). - coding style Abide by the general formatting of the code you are modifying. The code base generally follows the GNU standards in usermode code and the Linux kernel standards in runtime code. - commit messages In the git commit message, make the first line a brief (<=50 char) summary of the patch, and leave the second line blank. If you have trouble coming up with a concise summary, consider whether your patch might be better broken into smaller commits. For trivial changes, the summary alone may be sufficient, but most commits should include a paragraph or two giving more details about what the change is and why it is needed. Extra information like bugzilla numbers and mailing-list discussion links are appreciated as a supplement, but they are not a replacement for a real description. - test suites As far as practicable, changes should be accompanied by test cases to prevent future regressions. Tests should be run on at least x86, and ideally also on some 64-bit platform. The test suite is located under /src/testsuite and is based on dejagnu. "make check" runs unprivileged tests only against an uninstalled build tree. "make installcheck" runs all tests against an installed tree. Tests that don't require probe execution should go into new or modified files under the *{ok,ko} directories, which are scanned by corresponding systemtap.pass1-4/*.exp files. The "ko" tests are for expected (deliberate) errors. Tests that execute probes (pass 5) should include their own .exp/.stp files under any other appropriate systemtap.* testsuite subdirectory. To run a particular test or set of tests, do: cd testsuite make check RUNTESTFLAGS=testname.exp or make installcheck RUNTESTFLAGS=testname.exp To disambiguate among multiple tests with the same name, specify the directory as well -- for example: make installcheck RUNTESTFLAGS=systemtap.base/print.exp - translator Translator changes can easily invalidate tapsets and user script code. One must tread carefully and run regression tests rigorously. Both positive and negative polarity (expect-pass / expect-fail) test cases may need to be written to assert a bug fix. Script language changes should be documented in the stap.1 man page and emphasized in the NEWS file. - tapsets Tapset script files should demonstrate effective economy, and avoid conflicts with user and other tapset code. It may be necessary to prefix symbols with the tapset name to ensure systemtap-wide uniqueness. All "external interfaces" expected to be used by user scripts (or perhaps other tapsets) should be documented in stapfuncs.5, stapprobes.5. Major or incompatible changes should be mentioned in the NEWS file. Internal function, variable, probe identifiers should be prefixed with "_" for extra uniqueness, and not documented in the man pages. Tapsets should come with a tests cases that provide good test coverage. Every alias definition should be tested for pass-2 correctness. Every embedded-C routine should be tested for pass-4 buildability. As they are a security hazard, every tapset embedded-C routine should be pass-5 stress-tested for response to erroneous inputs. This applies doubly to /* unprivileged */ ones. The platforms/architectures against which the tapset was tested should be published, and ideally asserted by code. Embedded-C code should avoid making references to the runtime or other code possibly generated by the translator. Embedded-C code that dereferences pointers should use deref() type functions to check each individual operation if there exists a possibility that the function may be called with invalid pointers or pointer chains. - runtime Changes to the runtime can cause problems on different architectures or kernel versions. Luckily, many code mistakes show up easily in the pass-4 tests. - meta Proposed changes to these guidelines should be discussed on the mailing list. - git basics git clone ssh://sources.redhat.com/git/systemtap.git # build ; hack hack hack; test git commit # to your local repository, add nice commit message git pull # to make sure your copy is up to date & merged # last minute rebuild; retest git rebase origin/master # clean git commit of merge history git diff origin/master # final visual check git push # to the central one