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