This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
hacking rules
- From: "Frank Ch. Eigler" <fche at redhat dot com>
- To: systemtap at sources dot redhat dot com
- Date: Wed, 12 Oct 2005 15:08:50 -0400
- Subject: hacking rules
Hi -
I committed a set of guidelines for contributing to systemtap as the
file /src/HACKING. It would be nice for folks to apply them
retroactively as appropriate.
This text describes contribution procedures to systemtap. Please read
and understand them before sending them. Discussions take place on
the <systemtap@sources.redhat.com> 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, and
ChangeLog entries. 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 CVS 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. ChangeLog entries
are used for nontrivial changes to source or documentation files.
Some subdirectories have ChangeLog files of their own, so make sure
you find the correct ones to prepend.
- test suites
As far as practicable, changes should be accompanied by test cases
to prevent future regressions.
Tests that don't require probe execution should go into new or
modified files under /src/testsuite/, a simple automake-flavoured
bucket. Subdirectories exist for testing only up to pass 1
(parseok/parseko), pass 2 (semok/semko), pass 3 (transok,transko),
and pass 4 (buildok/buildko). The "ko" tests are for expected
(deliberate) errors.
Tests that execute probes (pass 5) go under /tests/testsuite/, a
dejagnu-based bucket that will require root access to run.
- 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.
- 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
tapset-wide uniqueness. All "external interfaces" expected to be
used by user scripts (or perhaps other tapsets) should be documented
in stapfuncs.5, stapprobes.5. Internal function, variable, probe
identifiers should be prefixed with "_" for extra uniqueness, and
not documented in the man pages.
New or changed embedded-C code should be accompanied by a test case
in the /src/testsuite/buildok/ bucket to assert its buildability,
and ideally pass-5 tests to assert correct behavour. Embedded-C
code should avoid making references to the runtime or other code
possibly generated by the translator.
- 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. [hunt: if appropriate, fill in information for
runtime self-testing code]
- meta
Proposed changes to these guidelines should be discussed on the
mailing list.