lib/CPANPLUS/Hacking.pod

   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