[Summary view] [Print] [Text view]

   1  =pod
   2  
   3  =head1 NAME
   4  
   5  CPANPLUS::Hacking
   6  
   7  =head1 DESCRIPTION
   8  
   9  This document attempts to describe how to easiest develop with the
  10  CPANPLUS environment, how certain things work and why.
  11  
  12  This is basically a quick-start guide to people who want to add
  13  features or patches to CPANPLUS.
  14  
  15  =head1 OBTAINING CPANPLUS
  16  
  17  CPANPLUS offers snapshots from the stable and unstable branches.
  18  After every patch to either of the branches, the snapshot is
  19  automatically updated.
  20  
  21  You can find the stable branch here (which should be equal to the
  22  CPAN release): L<http://p4.elixus.org/snap/cpanplus-dist.tar.gz>
  23  
  24  And the development branch here:
  25  L<http://p4.elixus.org/snap/cpanplus-devel.tar.gz>
  26  
  27  =head1 INSTALLING CPANPLUS
  28  
  29  CPANPLUS follows the standard perl module installation process:
  30  
  31      perl Makefile.PL
  32      make
  33      make test
  34      make install
  35  
  36  =head1 CONFIGURING CPANPLUS
  37  
  38  When running C<perl Makefile.PL> you will be prompted to configure.
  39  If you have already done so, and merely wish to update the C<Makefile>,
  40  simply run:
  41  
  42      perl Makefile.PL JFDI=1
  43  
  44  This will keep your configuration intact. Note however, if there are
  45  changes to the default configuration file C<Config.pm-orig>, you should
  46  either delete your current config file and reconfigure, or patch your
  47  config file from the new entries in C<Config.pm-orig>.
  48  
  49  =head1 RUNNING CPANPLUS FROM DEVELOPMENT ENVIRONMENT
  50  
  51  If you'd rather not install the development version to your
  52  C<site_perl> directory, that's no problem. You can set your C<PERL5LIB>
  53  environment variable to CPANPLUS' C<lib> directory, and you can run it
  54  from there.
  55  
  56  =head1 RUNNING CPANPLUS TESTS
  57  
  58  Tests are what tells us if CPANPLUS is working. If a test is not working,
  59  try to run it explicilty like this:
  60  
  61      perl -I/path/to/cpanplus/lib t/XX_name_of_test.t 1
  62  
  63  The extra '1' makes sure that all the messages and errors (they might
  64  be errors we're testing for!) are being printed rather than kept quiet.
  65  This is a great way to find out the context of any failures that may
  66  occur.
  67  
  68  If you believe this test failure proves a bug in CPANPLUS, the long
  69  output of the test file is something we'd like to see alongside your
  70  bug report.
  71  
  72  =head1 FINDING BUGS
  73  
  74  Sometimes you might find bugs in CPANPLUS' behaviour. If you encounter
  75  these in a development snapshot, we'd appreciate a complete patch (as
  76  described below in the L<SENDING PATCHES> section.
  77  
  78  If it's way over your head, then of course reporting the bug is always
  79  better than not reporting it at all. Before you do so though, make
  80  sure you have the B<latest> development snapshot, and the bug still
  81  persists there. If so, report the bug to this address:
  82  
  83      cpanplus-devel@lists.sourceforge.net
  84  
  85  A good C<patch> would have the following characteristics:
  86  
  87  =over 4
  88  
  89  =item Problem description
  90  
  91  Describe clearly what the bug is you found, and what it should have
  92  done instead.
  93  
  94  =item Program demonstrating the bug
  95  
  96  Show us how to reproduce the bug, in a simple of a program as possible
  97  
  98  =item [OPTIONAL] A patch to the test suite to test for the bug
  99  
 100  Amend our test suite by making sure this bug will be found in this, and
 101  future versions of CPANPLUS (see L<SUPPLYING PATCHES>)
 102  
 103  =item [OPTIONAL] A patch to the code + tests + documentation
 104  
 105  Fix the bug, update the docs & tests. That way your bug will be gone
 106  forever :)
 107  
 108  =back
 109  
 110  =head1 SUPPLYING PATCHES
 111  
 112  Patches are a good thing, and they are welcome. Especially if they fix
 113  bugs you've found along the way, or that others have reported.
 114  
 115  We prefer patches in the following format:
 116  
 117  =over 4
 118  
 119  =item * In C<diff -u> or C<diff -c> format
 120  
 121  =item * From the root of the snapshot
 122  
 123  =item * Including patches for code + tests + docs
 124  
 125  =item * Sent per mail to cpanplus-devel@lists.sourceforge.net
 126  
 127  =item * With subject containing C<[PATCH]> + description of the patch
 128  
 129  =back
 130  
 131  You will always be informed if a patch is applied or rejected, and in
 132  case of rejection why that is (perhaps you can tweak the patch to have
 133  it accepted after all).
 134  
 135  =cut
 136  
 137  __END__
 138  
 139  * perl5lib
 140  * perl t/foo 1
 141  * patches to cpanplus-devel
 142  * snap/devel.tgz