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   -- either in stapprobes.3stap if they are built into the language or
  94   otherwise somehow essential; or in kernel-doc style comments if they
  95   are defined in a tapset (see almost any existing tapset for an
  96   example of how this is done); any new tapset should be mentioned in
  97   doc/SystemTap_Tapset_Reference/tapsets.tmpl.  Major or incompatible
  98   changes should be mentioned in the NEWS file; see also the
  99   deprecation section below.
 100
 101   Internal function, variable, probe identifiers should be prefixed
 102   with "_" for extra uniqueness, and not documented in the man pages.
 103
 104   Tapsets should come with a tests cases that provide good test
 105   coverage.  Every alias definition should be tested for pass-2
 106   correctness.  Every embedded-C routine should be tested for pass-4
 107   buildability.  As they are a security hazard, every tapset
 108   embedded-C routine should be pass-5 stress-tested for response to
 109   erroneous inputs.  This applies doubly to /* unprivileged */ ones.
 110   The platforms/architectures against which the tapset was tested
 111   should be published, and ideally asserted by code.
 112
 113   Embedded-C code should avoid making references to the runtime or
 114   other code possibly generated by the translator.  Embedded-C code that
 115   dereferences pointers should use deref() type functions to check each
 116   individual operation if there exists a possibility that the function may
 117   be called with invalid pointers or pointer chains.
 118
 119 - deprecation
 120
 121   Try to remain compatible with existing valid scripts, with respect
 122   to changes in the script language or the tapset.  Where this is not
 123   practicable, preserve the old functionality using the %( systemtap_v %)
 124   preprocessor conditional in the tapset and systemtap_session.compatible
 125   in the translator.  If needed, after several major releases,
 126   deprecated functionality may be dropped outright.  Note both pending
 127   and final deprecation in NEWS and the permanent DEPRECATION section
 128   in stap.1.  The intent is to protect old scripts for a year or longer.
 129
 130   Tapset functions to be deprecated should be kept for at least one
 131   major release.  For example, if we're in development between versions
 132   1.2 and 1.3, wrap to-be-deprecated tapset functions or probes in
 133        %( systemtap_v <= "1.3" %?    function foo() {}   %)
 134   so as to preserve the tapset function during the life of the 1.3 release.
 135
 136   Script language changes that cause earlier valid scripts to become
 137   invalid should be opt-in (requiring --compatible=NEWVERSION) for at
 138   least one major release before becoming default.  For example, test
 139      strverscmp(s.compatible.c_str(), "1.4") >= 0
 140   in the 1.3 release sources in order to activate the change.
 141
 142 - runtime
 143
 144   Changes to the runtime can cause problems on different architectures
 145   or kernel versions.  Luckily, many code mistakes show up easily in
 146   the pass-4 tests.
 147
 148 - i18n
 149
 150   We use the zanata [1] system for managing translations of runtime
 151   strings.  If interested, create yourself a zanata account, and help
 152   translate online!  In addition, you can ship systemtap sources
 153   to/from zanata by installing the zanata-cli and getting a
 154   $HOME/.config/zanata.ini file, thereafter following the advice [2][3]
 155   of "make update-po" (invoked from the top of the build tree).
 156
 157   [1] https://translate.zanata.org/zanata/iteration/view/systemtap/master
 158   [2] http://zanata.org/help/cli/cli-push
 159   [3] http://zanata.org/help/cli/cli-pull
 160
 161 - meta
 162
 163   Proposed changes to these guidelines should be discussed on the
 164   mailing list.
 165
 166 - git basics
 167
 168   git clone ssh://sourceware.org/git/systemtap.git
 169   # OR: use git://sourceware.org/git/systemtap.git then add to .git/config:
 170   #     [remote "origin"]
 171   #     pushurl=ssh://sourceware.org/git/systemtap.git
 172   # build ; hack hack hack; test
 173   git add FILE1 FILE2 # enumerate all modified or new files
 174   git status # to confirm that needed local changes are "staged"
 175   git commit # to your local repository, add nice commit message
 176   git show # to check that the last commit included all changes
 177   git pull # to make sure your copy is up to date & merged
 178   # last minute rebuild; retest
 179   git rebase origin/master # clean git commit of merge history
 180   git diff origin/master # final visual check
 181   git push # to the central one
 182