HACKING

   1 We welcome your contributions to the Performance Co-Pilot project!
   2
   3 Our preferred method of exchanging code, documentation, tests and new
   4 ideas is via git.  To participate, create a cloned git tree using a
   5 public git hosting service (e.g. github) and send mail to the list
   6 with a description of the code and its location.
   7
   8 Patches are fine too - send 'em through to the list at any time - even
   9 just ideas, pseudo-code, etc - we've found it is often a good idea to
  10 seek early feedback, particularly when modelling the metrics you'll be
  11 exporting from any new PMDAs you might be writing.
  12
  13
  14 Philosophy
  15 ==========
  16
  17 PCP development has a long tradition of focussing on automated testing.
  18
  19 New tests should be added to the testsuite with new code.  This is not
  20 a hard requirement when sending out patches or git commits, however,
  21 particularly as a new contributor.  Someone else will work with you to
  22 introduce an appropriate level of testing to exercise your fix or new
  23 code, and that will end up being committed along with your new changes.
  24
  25 For the more practiced, regular PCP committers: testing is assumed to
  26 have been done for all commits - both regression testing, using all of
  27 the existing tests, and addition of new tests to exercise the commits.
  28 A guide to using the automated quality assurance test suite exists in
  29 the qa/README file.
  30
  31 For the very practiced, life members of the team: please help out in
  32 terms of getting new contributors moving with their patches - writing
  33 tests with them, giving feedback, and merging their code quickly.  We
  34 aim to have new PMDA or monitoring tool contributions included in the
  35 release immediately following the first arrival of code.  Also ensure
  36 attribution of other contributors code is handled correctly using the
  37 git-commit --author option.
  38
  39 Above all, have fun!
  40
  41
  42 Conventions
  43 ===========
  44
  45 Add permanent diagnostics to any code of middling-to-high complexity.
  46 The convention is to test the pmDebug variable (from libpcp) which is
  47 supported by every tool via the -D/--debug option - see pmdbg(1) for
  48 details, and see also the many examples of its use in existing code.
  49
  50 Use the same coding style used in the code surrounding your changes.
  51
  52 All the existing code is GPL'd, so feel free to borrow and adapt code
  53 that is similar to the function you want to implement.  This maximizes
  54 your chance of absorbing the "style" and "conventions" and producing
  55 code that others will be able to easily read, understand and refine.
  56
  57
  58 Practicalities
  59 ==============
  60
  61 Refer to the qa/README file for details on using the testsuite locally.
  62 When writing new tests, bear in mind that other people will be running
  63 those tests *alot*.  An ideal test is one that:
  64
  65 ...is small - several small tests trump one big test
  66    (allowing someone else debugging a test failure to quickly get their
  67     head around what the test does)
  68
  69 ...runs in as short an amount of time as possible
  70    (allowing someone debugging a failure to iterate quickly through any
  71     ideas they have while working on the fix)
  72
  73 ...uses the same style as all the other tests in the "qa" directory
  74    (other people will be debugging tests you write and you may need to
  75     debug other peoples tests as well - sticking to the same script
  76     style and conventions is universally helpful)
  77
  78 ...uses filtering intelligently ... because tests pass or fail based
  79    on textual comparison of observed and expected output, it is critical
  80    to filter out the fluff (remove it or make it determinisitic) and
  81    retain the essence of what the test is exercising.  See common.filter
  82    for some useful filtering functions, and watch out for things like:
  83    o dates and times (unless using archives)
  84    o use -z when using archives so the results are not dependent on
  85      the timezone where the test is run
  86    o the pid of the running test, especially when part of $tmp that is
  87      used extensively
  88    o collating sequences and locale ... take explicit control if in doubt
  89
  90
  91 ...is portable, testing as many platforms as possible, for example:
  92    o  use pmdasample rather than a pmda<kernel> metric;
  93    o  use archives for exercising exact behaviour of monitoring tools;
  94    o  watch out for differences in output between system utilities;
  95    o  before running, test for situations where it cannot run - such
  96       as unsupported platforms/configurations - use _notrun() here.
  97