* new file

1 files changed, 90 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 00000000..436048b3
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,90 @@
+This text describes contribution procedures to systemtap.  Please read
+and understand them before sending them.  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 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
+  tapset-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.
+
+  New or changed embedded-C code should be accompanied by a test case
+  in the /src/testsuite/buildok/ bucket to assert its buildability,
+  and ideally pass-5 tests to assert correct behavour.  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.