Edit File: Hacking.pod
=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