forked from Perl-Toolchain-Gang/ExtUtils-MakeMaker
/
CONTRIBUTING
205 lines (131 loc) · 6.34 KB
/
CONTRIBUTING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
"The easy way is always mined.
The important things are always simple.
The simple things are always hard."
-- Some of Murphy's Laws of Combat
This is a short set of guidelines for those contributing
ExtUtils::MakeMaker. It's not an iron-clad set of rules, but just
things which make life easier when reading and integrating a patch.
Reporting bugs
- Often the only information we have for fixing a bug is contained in your
report. So...
- Please report your bugs via http://rt.cpan.org or
https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker/issues or
by mailing to makemaker@perl.org.
RT or GitHub are preferred.
- Please report your bug immediately upon encountering it. Do not wait
until you have a patch to fix the bug. Patches are good, but not at
the expense of timely bug reports.
- Please be as verbose as possible. Include the complete output of
your 'make test' or even 'make test TEST_VERBOSE=1' and a copy of the
generated Makefile. Err on the side of verbosity. The more data we
have to work with, the faster we can diagnose the problem.
- If you find an undocumented feature, or if a feature has changed/been
added which causes a problem, report it. Do not assume it was done
deliberately. Even if it was done deliberately, we still want to hear
if it caused problems.
- If you're testing MakeMaker against a development version of Perl,
please also check it against the latest stable version. This makes it
easier to figure out if it's MakeMaker or Perl at fault.
Pull Request
- If you wrote a patch already, please Pull Request on GitHub.
- Pull Request against the latest development snapshot from GitHub
repository are preferred.
- Pull Request against the latest CPAN version are ok, too.
Code formatting
- No literal tabs (except where necessary inside Makefile code, obviously).
- 4 character indentation.
- this_style is preferred instead of studlyCaps.
- Private subroutine names (ie. those used only in the same package
they're declared in) should start with an underscore (_sekret_method).
- Protected subroutines (ie. ones intended to be used by other modules in
ExtUtils::*) should be named normally (no leading underscore) but
documented as protected (see Documentation below).
- Do not use indirect object syntax (ie. new Foo::Bar (@args))
- make variables use dollar signs like Perl scalars. This causes problems
when you have to mix them both in a string. If you find yourself
backwacking lots of dollar signs because you have one interpolated
perl variable, like this:
return <<EOT;
subdirs ::
\$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)
EOT
or are switching quoting contexts:
return q{
subdirs ::
$(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
};
consider using sprintf instead.
return sprintf <<'EOT', $subdir;
subdirs ::
$(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
EOT
Refactoring and Cleanup
- MakeMaker is a mess. We like patches which clean things up.
Backwards Compatibility
- MakeMaker must be backwards compatible to 5.6.2.
Avoid any obvious 5.8-isms.
- MakeMaker should avoid having module dependencies.
But if new code need depends the modules absolutely,
it will bundle the modules.
See Makefile.PL of ExtUtils::MakeMaker for detail.
Cross-Platform Compatibility
- MakeMaker must work on all architectures Perl works on (see perlport.pod).
This means all Unixen (including Cygwin and MacOS X), Windows, and VMS.
- Use the available macros rather than shell commands $(MV), $(CP),
$(TOUCH), etc...
- MakeMaker must work on many makes. GNU, BSD, Solaris, nmake, dmake, MMS
and MMK to name the most common. Keep your make code as simple as
possible.
- Avoid special make variables (even $@).
- Format targets as "target : dependency", the spacing is important.
- Use $(NOECHO) instead of @.
- Use - to tell make to ignore the exit code of a command. (Unfortunately,
some make variants don't honor an $(IGNORE) macro).
- Always put a space between $(NOECHO) and the command.
- Always put a space between - (ignore) and the command.
- Always put $(NOECHO) and - together, no space between them.
# Right
-$(NOECHO) command
$(NOECHO) command
- command
- Often when you patch ExtUtils::MM_Unix, similar patches must be done
to the other MM_* modules. If you can, please do this extra work
otherwise I have to. If you can't, that's ok. We can help.
- If possible, please test your patch on two Very Different architectures.
Unix, Windows and VMS being Very Different. Note: Cygwin and OS X are
Unixen for our purposes.
- If nothing else, at least try it on two different Unixen machines
(ie. Linux and OS X).
- If you find yourself writing "do_this if $^O eq 'That'" (ie. checks on
the OS type) perhaps your code belongs in one of the non-Unix MM_*
modules (ie. MM_Win32, MM_VMS, etc...). If one does not exist, consider
creating one. It's ok to have an MM_* module with only one method.
- Some shells have very small buffers. This means command lines must
be as small as possible. If your command is just too long, consider
making it an ExtUtils::Command::MM function. If your command might
receive many arguments (such as pod2man or pm_to_blib) consider
using split_command() to split it into several, shorter calls.
- Most shells quote differently. If you need to put a perl one-liner
in the Makefile, please use oneliner() to generate it.
Tests
- Tests would be nice, but I'm not going to pretend testing MakeMaker
is easy. If nothing else, let us know how you tested your patch by
hand. It does really help everyone if you can improve tests, though!
- Travis CI (https://travis-ci.org) is good sources of testing
machines of many perl versions. Accounts are free.
Documentation
- Documentation would be nice.
- If the new feature/method is private, please document it with POD
wrapped in "=begin/end private" tags. That way it will be documented,
but won't be displayed (future versions of perldoc may have options
to display).
=begin private
=head3 _foo_bar
$mm->_foo_bar
Blah blah blah
=end private
=cut
sub _foo_bar {
...
- If you're overriding a method, document that it's an override and
*why* it's being overridden. Don't repeat the original documentation.