Version bumps for 0.9.6 release

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