HACKING

This text describes contribution procedures to systemtap.  Please read
and understand them before jumping in.  Discussions take place on
the <systemtap@sourceware.org> 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
  -- either in stapprobes.3stap if they are built into the language or
  otherwise somehow essential; or in kernel-doc style comments if they
  are defined in a tapset (see almost any existing tapset for an
  example of how this is done); any new tapset should be mentioned in
  doc/SystemTap_Tapset_Reference/tapsets.tmpl.  Major or incompatible
  changes should be mentioned in the NEWS file; see also the
  deprecation section below.

  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.

- deprecation

  Try to remain compatible with existing valid scripts, with respect
  to changes in the script language or the tapset.  Where this is not
  practicable, preserve the old functionality using the %( systemtap_v %)
  preprocessor conditional in the tapset and systemtap_session.compatible
  in the translator.  If needed, after several major releases,
  deprecated functionality may be dropped outright.  Note both pending
  and final deprecation in NEWS and the permanent DEPRECATION section
  in stap.1.  The intent is to protect old scripts for a year or longer.

  Tapset functions to be deprecated should be kept for at least one
  major release.  For example, if we're in development between versions
  1.2 and 1.3, wrap to-be-deprecated tapset functions or probes in 
       %( systemtap_v <= "1.3" %?    function foo() {}   %)
  so as to preserve the tapset function during the life of the 1.3 release.

  Script language changes that cause earlier valid scripts to become
  invalid should be opt-in (requiring --compatible=NEWVERSION) for at
  least one major release before becoming default.  For example, test
     strverscmp(s.compatible.c_str(), "1.4") >= 0
  in the 1.3 release sources in order to activate the change.

- 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://sourceware.org/git/systemtap.git
  # OR: use git://sourceware.org/git/systemtap.git then add to .git/config:
  #     [remote "origin"]
  #     pushurl=ssh://sourceware.org/git/systemtap.git
  # build ; hack hack hack; test
  git add FILE1 FILE2 # enumerate all modified or new files
  git status # to confirm that needed local changes are "staged"
  git commit # to your local repository, add nice commit message
  git show # to check that the last commit included all changes
  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