2006-08-11 David Smith <dsmith@redhat.com>

[systemtap.git] / HACKING

This text describes contribution procedures to systemtap.  Please read
and understand them before jumping in.  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 should be run on at least
  x86, and ideally also on some 64-bit platform.

  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
  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.  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 and ideally
  pass-5 correctness.  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.

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