| =pod |
| |
| =head1 NAME |
| |
| CPANPLUS::Hacking - developing CPANPLUS |
| |
| =head1 DESCRIPTION |
| |
| This document attempts to describe how to develop with the |
| CPANPLUS environment most easily, how certain things work and why. |
| |
| This is basically a quick-start guide to people who want to add |
| features or patches to CPANPLUS. |
| |
| =head1 OBTAINING CPANPLUS |
| |
| Checkout CPANPLUS from its GIT repository at |
| L<https://github.com/jib/cpanplus-devel> . |
| |
| =head1 INSTALLING CPANPLUS |
| |
| CPANPLUS follows the standard perl module installation process: |
| |
| perl Makefile.PL |
| make |
| make test |
| make install |
| |
| =head1 CONFIGURING CPANPLUS |
| |
| When running C<perl Makefile.PL> you will be prompted to configure. |
| If you have already done so, and merely wish to update the C<Makefile>, |
| simply run: |
| |
| perl Makefile.PL JFDI=1 |
| |
| This will keep your configuration intact. Note however, if there are |
| changes to the default configuration file C<Config.pm-orig>, you should |
| either delete your current config file and reconfigure, or patch your |
| config file from the new entries in C<Config.pm-orig>. |
| |
| =head1 RUNNING CPANPLUS FROM DEVELOPMENT ENVIRONMENT |
| |
| If you'd rather not install the development version to your |
| C<site_perl> directory, that's no problem. You can set your C<PERL5LIB> |
| environment variable to CPANPLUS' C<lib> directory, and you can run it |
| from there. |
| |
| =head1 RUNNING CPANPLUS TESTS |
| |
| Tests are what tells us if CPANPLUS is working. If a test is not working, |
| try to run it explicitly like this: |
| |
| perl -I/path/to/cpanplus/lib t/XX_name_of_test.t 1 |
| |
| The extra '1' makes sure that all the messages and errors (they might |
| be errors we're testing for!) are being printed rather than kept quiet. |
| This is a great way to find out the context of any failures that may |
| occur. |
| |
| If you believe this test failure proves a bug in CPANPLUS, the long |
| output of the test file is something we'd like to see alongside your |
| bug report. |
| |
| =head1 FINDING BUGS |
| |
| Sometimes you might find bugs in CPANPLUS' behaviour. If you encounter |
| these in a development snapshot, we'd appreciate a complete patch (as |
| described below in the L<SENDING PATCHES> section. |
| |
| If it's way over your head, then of course reporting the bug is always |
| better than not reporting it at all. Before you do so though, make |
| sure you have the B<latest> development snapshot, and the bug still |
| persists there. If so, report the bug to this address: |
| |
| bug-cpanplus@rt.cpan.org |
| |
| A good C<patch> would have the following characteristics: |
| |
| =over 4 |
| |
| =item Problem description |
| |
| Describe clearly what the bug is you found, and what it should have |
| done instead. |
| |
| =item Program demonstrating the bug |
| |
| Show us how to reproduce the bug, in a simple of a program as possible |
| |
| =item [OPTIONAL] A patch to the test suite to test for the bug |
| |
| Amend our test suite by making sure this bug will be found in this, and |
| future versions of CPANPLUS (see L<SUPPLYING PATCHES>) |
| |
| =item [OPTIONAL] A patch to the code + tests + documentation |
| |
| Fix the bug, update the docs & tests. That way your bug will be gone |
| forever :) |
| |
| =back |
| |
| =head1 SUPPLYING PATCHES |
| |
| Patches are a good thing, and they are welcome. Especially if they fix |
| bugs you've found along the way, or that others have reported. |
| |
| We prefer patches in the following format: |
| |
| =over 4 |
| |
| =item * In C<diff -u> or C<diff -c> format |
| |
| =item * From the root of the snapshot |
| |
| =item * Including patches for code + tests + docs |
| |
| =item * Sent per mail to bug-cpanplus@rt.cpan.org |
| |
| =item * With subject containing C<[PATCH]> + description of the patch |
| |
| =back |
| |
| You will always be informed if a patch is applied or rejected, and in |
| case of rejection why that is (perhaps you can tweak the patch to have |
| it accepted after all). |
| |
| =cut |
| |
| __END__ |
| |
| * perl5lib |
| * perl t/foo 1 |
| * patches to cpanplus-devel |
| * snap/devel.tgz |
