File: HACKING.pod

package info (click to toggle)
libtest-harness-perl 3.12-1
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 1,456 kB
  • ctags: 550
  • sloc: perl: 16,945; makefile: 44; sh: 12
file content (262 lines) | stat: -rw-r--r-- 6,283 bytes parent folder | download
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
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262

# this is in pod format (try `perldoc HACKING.pod`)

=pod

=head1 NAME

HACKING.pod - contributing to TAP::Harness

=head1 ABOUT

This is the guide for TAP::Harness internals contributors (developers,
testers, documenters.)

If you are looking for more information on how to I<use> TAP::Harness,
you probably want
L<http://testanything.org/wiki/index.php/TAP::Parser_Cookbook> instead.

=head1 Getting Started

See the resources section in I<META.yml> or I<Build.PL> for links to the
project mailing list, bug tracker, svn repository, etc.

For ease of reference, at the time of writing the SVN repository was at:

  http://svn.hexten.net/tapx

To get the latest version of trunk:

  svn co http://svn.hexten.net/tapx/trunk

For best results, read the rest of this file, check RT for bugs which
scratch your itch, join the mailing list, etc.

=head1 Formatting

=head2 perltidy

The project comes with a C<.perltidyrc>, which perltidy will
automatically use if the project root is your working directory.  This
is setup by default to read and write the perl code on a pipe.  To
configure your editor:

=over 4

=item * vim

In C<.vimrc>, you can add the following lines:

 nnoremap <Leader>pt :%!perltidy -q<cr> " only work in 'normal' mode
 vnoremap <Leader>pt :!perltidy -q<cr>  " only work in 'visual' mode

In other words, if your C<Leader> is a backslash, you can type C<\pt> to
reformat the file using the C<.perltidyrc>.  If you are in visual mode
(selecting lines with shift-v), then only the code you have currently have
selected will be reformattted.

=item * emacs

For emacs, you can use this snippet from Sam Tregar
(L<http://use.perl.org/~samtregar/journal/30185>):

 (defun perltidy-region ()
    "Run perltidy on the current region."
    (interactive)
    (save-excursion
      (shell-command-on-region (point) (mark) "perltidy -q" nil t)
      (cperl-mode)))

 (defun perltidy-all ()
    "Run perltidy on the current region."
    (interactive)
    (let ((p (point)))
      (save-excursion
        (shell-command-on-region (point-min) (point-max) "perltidy -q" nil t)
        )
      (goto-char p)
      (cperl-mode)))

 (global-set-key "\M-t" `perltidy-region)
 (global-set-key "\M-T" `perltidy-all) 

=back

=head1 Tests and Coverage

...

=for eric_not_it
  TODO link to a good guide on writing tests for TAP::Parser

=head1 Writing for Compatibility

...

=for eric_not_it
  TODO explain no bundling, PERL_CORE, etc

=head1 Use TAP::Object

TAP::Object is the common base class to all TAP::* modules, and should be for
any that you write.

=head1 Exception Handling

Exceptions should be raised with L<Carp>:

  require Carp;
  Carp::croak("Unsupported syntax version: $version");

  require Carp;
  Carp::confess("Unsupported syntax version: $version");

=head1 Deprecation cycle

Any I<documented> sub that needs to be changed or removed (and would therefore
cause a backwards-compat issue) must go through a deprecation cycle to give
developers a chance to adjust:

  1. Document the deprecation
  2. Release
  3. Change the code
  4. Release

=head1 Documentation

The end-user and API documentation is all in the 'lib/' directory.  In
.pm files, the pod is "inline" to the code.  See L<perlpod> for more
about pod.

=head2 Pod Commands

For compatibility's sake, we do not use the =head3 and =head4 commands.

=over

=item C<=head1 SECTION>

Sections begin with an C<=head1> command and are all-caps.

=for eric_not_it
  I guess... Mixed case messes with various pod hacking tools.

  NAME
  VERSION
  SYNOPSIS
  CONSTRUCTOR
  METHODS
  CLASS METHODS
  SOME OTHER SORT OF METHODS
  SEE ALSO

=item C<=head2 method>

=for eric_not_it
  The following is how I would do it, but opposite of what we have.

The C<=head2> command documents a method.  The name of the method should have no adornment (e.g. don't CE<lt>method> or CE<lt>method($list, $of, $params)>.)

These sections should begin with a short description of what the method
does, followed by one or more examples of usage.  If needed, elaborate
on the subtleties of the parameters and context after (and/or between)
the example(s).

  =head2 this_method

  This method does some blah blah blah.

    my @answer = $thing->this_method(@arguments);

  =head2 that_thing

  Returns true if the thing is true.

    if($thing->that_thing) {
      ...
    }

=item C<=item parameter>

Use C<=item> commands for method arguments and parameters (and etc.)  In
most html pod formatters, these I<do not> get added to the
table-of-contents at the top of the page.

=back

=head2 Pod Formatting Codes

=over

=item LE<lt>Some::Module>

Be careful of the wording of C<LE<lt>Some::ModuleE<gt>>.  Older pod
formatters would render this as "the Some::Module manpage", so it is
best to either word your links as "C<(see E<lt>Some::ModuleE<gt> for
details.)>" or use the "explicit rendering" form of
"C<E<lt>Some::Module|Some::ModuleE<gt>>".

=back

=head2 VERSION

The version numbers are updated by L<Perl::Version>.

=head2 DEVELOPER DOCS/NOTES

The following "formats" are used with C<=begin>/C<=end> and C<=for>
commands for pod which is not part of the public end-user/API
documentation.

=over

=item note

Use this if you are uncertain about a change to some pod or think it
needs work.

  =head2 some_method

    ...

  =for note
    This is either falsely documented or a bug -- see ...

=item developer

  =begin developer

  Long-winded explanation of why some code is the way it is or various
  other subtleties which might incite head-scratching and WTF'ing.

  =end developer

=item deprecated

  =for deprecated
    removed in 0.09, kill by ~0.25

=back

=head1 Committing to Subversion

If you have commit access, please bear this in mind.

Development is done either on trunk or a branch, as appropriate:

If it's something that might be controversial, break the build or take a long
time (more than a couple of weeks) to complete then it'd probably be
appropriate to branch. Otherwise it can go in trunk.

If in doubt discuss it on the mailing list before you commit.

=cut

=for developer
... or whatever.  I'm just making stuff up here.  If any of this is
wrong, please correct it.  To the extent that there is an "official
policy", it should be written down. --Eric

=cut

# vim:ts=2:sw=2:et:sta