1HACKING(3)            User Contributed Perl Documentation           HACKING(3)
2
3
4

NAME

6       HACKING.pod - contributing to TAP::Harness
7

ABOUT

9       This is the guide for TAP::Harness internals contributors (developers,
10       testers, documenters.)
11
12       If you are looking for more information on how to use TAP::Harness, you
13       probably want
14       <http://testanything.org/testing-with-tap/perl/tap-parser-cookbook.html>
15       instead.
16

Getting Started

18       See the resources section in META.yml or Build.PL for links to the
19       project mailing list, bug tracker, svn repository, etc.
20
21       For ease of reference, at the time of writing the SVN repository was
22       at:
23
24         http://svn.hexten.net/tapx
25
26       To get the latest version of trunk:
27
28         git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git
29
30       For best results, read the rest of this file, check RT for bugs which
31       scratch your itch, join the mailing list, etc.
32

Formatting

34   perltidy
35       The project comes with a ".perltidyrc", which perltidy will
36       automatically use if the project root is your working directory.  This
37       is setup by default to read and write the perl code on a pipe.  To
38       configure your editor:
39
40       •   vim
41
42           In ".vimrc", you can add the following lines:
43
44            nnoremap <Leader>pt :%!perltidy -q<cr> " only work in 'normal' mode
45            vnoremap <Leader>pt :!perltidy -q<cr>  " only work in 'visual' mode
46
47           In other words, if your "Leader" is a backslash, you can type "\pt"
48           to reformat the file using the ".perltidyrc".  If you are in visual
49           mode (selecting lines with shift-v), then only the code you have
50           currently have selected will be reformatted.
51
52       •   emacs
53
54           For emacs, you can use this snippet from Sam Tregar
55           (<http://use.perl.org/~samtregar/journal/30185>):
56
57            (defun perltidy-region ()
58               "Run perltidy on the current region."
59               (interactive)
60               (save-excursion
61                 (shell-command-on-region (point) (mark) "perltidy -q" nil t)
62                 (cperl-mode)))
63
64            (defun perltidy-all ()
65               "Run perltidy on the current region."
66               (interactive)
67               (let ((p (point)))
68                 (save-excursion
69                   (shell-command-on-region (point-min) (point-max) "perltidy -q" nil t)
70                   )
71                 (goto-char p)
72                 (cperl-mode)))
73
74            (global-set-key "\M-t" `perltidy-region)
75            (global-set-key "\M-T" `perltidy-all)
76

Tests and Coverage

78       ...
79

Writing for Compatibility

81       ...
82

Use TAP::Object

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

Exception Handling

88       Exceptions should be raised with Carp:
89
90         require Carp;
91         Carp::croak("Unsupported syntax version: $version");
92
93         require Carp;
94         Carp::confess("Unsupported syntax version: $version");
95

Deprecation cycle

97       Any documented sub that needs to be changed or removed (and would
98       therefore cause a backwards-compat issue) must go through a deprecation
99       cycle to give developers a chance to adjust:
100
101         1. Document the deprecation
102         2. Carp a suitable message
103         3. Release
104         4. Change the code
105         5. Release
106

Documentation

108       The end-user and API documentation is all in the 'lib/' directory.  In
109       .pm files, the pod is "inline" to the code.  See perlpod for more about
110       pod.
111
112   Pod Commands
113       For compatibility's sake, we do not use the =head3 and =head4 commands.
114
115       "=head1 SECTION"
116           Sections begin with an "=head1" command and are all-caps.
117
118             NAME
119             VERSION
120             SYNOPSIS
121             CONSTRUCTOR
122             METHODS
123             CLASS METHODS
124             SOME OTHER SORT OF METHODS
125             SEE ALSO
126
127       "=head2 method"
128           The "=head2" command documents a method.  The name of the method
129           should have no adornment (e.g. don't C<method> or C<method($list,
130           $of, $params)>.)
131
132           These sections should begin with a short description of what the
133           method does, followed by one or more examples of usage.  If needed,
134           elaborate on the subtleties of the parameters and context after
135           (and/or between) the example(s).
136
137             =head2 this_method
138
139             This method does some blah blah blah.
140
141               my @answer = $thing->this_method(@arguments);
142
143             =head2 that_thing
144
145             Returns true if the thing is true.
146
147               if($thing->that_thing) {
148                 ...
149               }
150
151       "=item parameter"
152           Use "=item" commands for method arguments and parameters (and etc.)
153           In most html pod formatters, these do not get added to the table-
154           of-contents at the top of the page.
155
156   Pod Formatting Codes
157       L<Some::Module>
158           Be careful of the wording of "L<Some::Module>".  Older pod
159           formatters would render this as "the Some::Module manpage", so it
160           is best to either word your links as ""(see <Some::Module> for
161           details.)"" or use the "explicit rendering" form of
162           ""<Some::Module|Some::Module>"".
163
164   VERSION
165       The version numbers are updated by Perl::Version.
166
167   DEVELOPER DOCS/NOTES
168       The following "formats" are used with "=begin"/"=end" and "=for"
169       commands for pod which is not part of the public end-user/API
170       documentation.
171
172       note
173           Use this if you are uncertain about a change to some pod or think
174           it needs work.
175
176             =head2 some_method
177
178               ...
179
180             =for note
181               This is either falsely documented or a bug -- see ...
182
183       developer
184             =begin developer
185
186             Long-winded explanation of why some code is the way it is or various
187             other subtleties which might incite head-scratching and WTF'ing.
188
189             =end developer
190
191       deprecated
192             =for deprecated
193               removed in 0.09, kill by ~0.25
194

Committing to Subversion

196       If you have commit access, please bear this in mind.
197
198       Development is done either on trunk or a branch, as appropriate:
199
200       If it's something that might be controversial, break the build or take
201       a long time (more than a couple of weeks) to complete then it'd
202       probably be appropriate to branch. Otherwise it can go in trunk.
203
204       If in doubt discuss it on the mailing list before you commit.
205
206
207
208perl v5.38.0                      2023-10-03                        HACKING(3)
Impressum