HACKING

   1 This text describes contribution procedures to systemtap.  Please read
   2 and understand them before jumping in.  Discussions take place on
   3 the <systemtap@sourceware.org> mailing list.
   4
   5 - general
   6
   7   Submissions should be in an easy-to-read diff/patch form, unless
   8   this is inappropriate due to size, relevance, or fraction of novel
   9   content.  They should be accompanied by an explanation.  The
  10   relevant test suites should be run before and after your changes,
  11   and regressions avoided, explained, or corrected.
  12
  13   Established contributors may be considered for direct GIT write
  14   access.  Other contributors should simply pack up the goods into a
  15   plain text email message to the mailing list.
  16
  17 - obvious changes
  18
  19   Trivial, obvious patches may be posted or committed without other
  20   formalities.
  21
  22 - copyright
  23
  24   You must designate the appropriate copyright holder for your
  25   contribution.  If not already there, this name should be added by
  26   your patch to the copyright header in the affected files.  The
  27   copyright holder is assumed to agree with the general licensing
  28   terms (GPLv2+).
  29
  30 - coding style
  31
  32   Abide by the general formatting of the code you are modifying.  The
  33   code base generally follows the GNU standards in usermode code and
  34   the Linux kernel standards in runtime code.
  35
  36 - commit messages
  37
  38   In the git commit message, make the first line a brief (<=50 char)
  39   summary of the patch, and leave the second line blank.  If you have
  40   trouble coming up with a concise summary, consider whether your
  41   patch might be better broken into smaller commits.
  42
  43   For trivial changes, the summary alone may be sufficient, but most
  44   commits should include a paragraph or two giving more details about
  45   what the change is and why it is needed.  Extra information like
  46   bugzilla numbers and mailing-list discussion links are appreciated
  47   as a supplement, but they are not a replacement for a real
  48   description.
  49
  50 - test suites
  51
  52   As far as practicable, changes should be accompanied by test cases
  53   to prevent future regressions.  Tests should be run on at least
  54   x86, and ideally also on some 64-bit platform.  The test suite is
  55   located under /src/testsuite and is based on dejagnu.  "make check"
  56   runs unprivileged tests only against an uninstalled build tree.
  57   "make installcheck" runs all tests against an installed tree.
  58
  59   Tests that don't require probe execution should go into new or
  60   modified files under the *{ok,ko} directories, which are scanned
  61   by corresponding systemtap.pass1-4/*.exp files.  The "ko" tests are
  62   for expected (deliberate) errors.
  63
  64   Tests that execute probes (pass 5) should include their own .exp/.stp
  65   files under any other appropriate systemtap.* testsuite subdirectory.
  66
  67   To run a particular test or set of tests, do:
  68     cd testsuite
  69     make check RUNTESTFLAGS=testname.exp
  70   or
  71     make installcheck RUNTESTFLAGS=testname.exp
  72   To disambiguate among multiple tests with the same name, specify
  73   the directory as well -- for example:
  74     make installcheck RUNTESTFLAGS=systemtap.base/print.exp
  75
  76 - translator
  77
  78   Translator changes can easily invalidate tapsets and user script
  79   code.  One must tread carefully and run regression tests rigorously.
  80   Both positive and negative polarity (expect-pass / expect-fail) test
  81   cases may need to be written to assert a bug fix.  Script language
  82   changes should be documented in the stap.1 man page and emphasized
  83   in the NEWS file.
  84
  85 - tapsets
  86
  87   Tapset script files should demonstrate effective economy, and avoid
  88   conflicts with user and other tapset code.
  89
  90   It may be necessary to prefix symbols with the tapset name to ensure
  91   systemtap-wide uniqueness.  All "external interfaces" expected to be
  92   used by user scripts (or perhaps other tapsets) should be documented
  93   in stapfuncs.5, stapprobes.5.  Major or incompatible changes should
  94   be mentioned in the NEWS file; see also the deprecation section below.
  95
  96   Internal function, variable, probe identifiers should be prefixed
  97   with "_" for extra uniqueness, and not documented in the man pages.
  98
  99   Tapsets should come with a tests cases that provide good test
 100   coverage.  Every alias definition should be tested for pass-2
 101   correctness.  Every embedded-C routine should be tested for pass-4
 102   buildability.  As they are a security hazard, every tapset
 103   embedded-C routine should be pass-5 stress-tested for response to
 104   erroneous inputs.  This applies doubly to /* unprivileged */ ones.
 105   The platforms/architectures against which the tapset was tested
 106   should be published, and ideally asserted by code.
 107
 108   Embedded-C code should avoid making references to the runtime or
 109   other code possibly generated by the translator.  Embedded-C code that
 110   dereferences pointers should use deref() type functions to check each
 111   individual operation if there exists a possibility that the function may
 112   be called with invalid pointers or pointer chains.
 113
 114 - deprecation
 115
 116   Try to remain compatible with existing valid scripts, with respect
 117   to changes in the script language or the tapset.  Where this is not
 118   practicable, preserve the old functionality using the %( systemtap_v %)
 119   preprocessor conditional in the tapset and systemtap_session.compatible
 120   in the translator.  If needed, after several major releases,
 121   deprecated functionality may be dropped outright.  Note both pending
 122   and final deprecation in NEWS and the permanent DEPRECATION section
 123   in stap.1.  The intent is to protect old scripts for a year or longer.
 124
 125   Tapset functions to be deprecated should be kept for at least one
 126   major release.  For example, if we're in development between versions
 127   1.2 and 1.3, wrap to-be-deprecated tapset functions or probes in
 128        %( systemtap_v <= "1.3" %?    function foo() {}   %)
 129   so as to preserve the tapset function during the life of the 1.3 release.
 130
 131   Script language changes that cause earlier valid scripts to become
 132   invalid should be opt-in (requiring --compatible=NEWVERSION) for at
 133   least one major release before becoming default.  For example, test
 134      strverscmp(s.compatible.c_str(), "1.4") >= 0
 135   in the 1.3 release sources in order to activate the change.
 136
 137 - runtime
 138
 139   Changes to the runtime can cause problems on different architectures
 140   or kernel versions.  Luckily, many code mistakes show up easily in
 141   the pass-4 tests.
 142
 143 - meta
 144
 145   Proposed changes to these guidelines should be discussed on the
 146   mailing list.
 147
 148 - git basics
 149
 150   git clone ssh://sourceware.org/git/systemtap.git
 151   # OR: use git://sourceware.org/git/systemtap.git then add to .git/config:
 152   #     [remote "origin"]
 153   #     pushurl=ssh://sourceware.org/git/systemtap.git
 154   # build ; hack hack hack; test
 155   git add FILE1 FILE2 # enumerate all modified or new files
 156   git status # to confirm that needed local changes are "staged"
 157   git commit # to your local repository, add nice commit message
 158   git show # to check that the last commit included all changes
 159   git pull # to make sure your copy is up to date & merged
 160   # last minute rebuild; retest
 161   git rebase origin/master # clean git commit of merge history
 162   git diff origin/master # final visual check
 163   git push # to the central one
 164