Commit | Line | Data |
6aaee015 |
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 |