HACKING.pod - contributing to TAP::Harness
This is the guide for TAP::Harness internals contributors (developers, testers,
If you are looking for more information on how to use
See the resources section in META.yml
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:
To get the latest version of trunk:
git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git
For best results, read the rest of this file, check RT for bugs which scratch
your itch, join the mailing list, etc.
The project comes with a ".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
In ".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 "Leader" is a backslash, you can type
"\pt" to reformat the file using the ".perltidyrc". If
you are in visual mode (selecting lines with shift-v), then only the code
you have currently have selected will be reformatted.
For emacs, you can use this snippet from Sam Tregar
(defun perltidy-region ()
"Run perltidy on the current region."
(shell-command-on-region (point) (mark) "perltidy -q" nil t)
(defun perltidy-all ()
"Run perltidy on the current region."
(let ((p (point)))
(shell-command-on-region (point-min) (point-max) "perltidy -q" nil t)
(global-set-key "\M-t" `perltidy-region)
(global-set-key "\M-T" `perltidy-all)
TAP::Object is the common base class to all TAP::* modules, and should be for
any that you write.
Exceptions should be raised with Carp:
Carp::croak("Unsupported syntax version: $version");
Carp::confess("Unsupported syntax version: $version");
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. Carp a suitable message
4. Change the code
The end-user and API documentation is all in the 'lib/' directory. In .pm files,
the pod is "inline" to the code. See perlpod for more about pod.
For compatibility's sake, we do not use the =head3 and =head4 commands.
- "=head1 SECTION"
- Sections begin with an "=head1" command and are all-caps.
SOME OTHER SORT OF METHODS
- "=head2 method"
- The "=head2" command documents a method. The name of the method
should have no adornment (e.g. don't C<method> or C<method($list,
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
This method does some blah blah blah.
my @answer = $thing->this_method(@arguments);
Returns true if the thing is true.
- "=item parameter"
- Use "=item" commands for method arguments and parameters (and
etc.) In most html pod formatters, these do not get added to the
table-of-contents at the top of the page.
- Be careful of the wording of "L<Some::Module>". Older pod
formatters would render this as "the Some::Module manpage", so
it is best to either word your links as ""(see
<Some::Module> for details.)"" or use the "explicit
rendering" form of
The version numbers are updated by Perl::Version.
The following "formats" are used with
"=begin"/"=end" and "=for" commands for pod
which is not part of the public end-user/API documentation.
- Use this if you are uncertain about a change to some pod or think it needs
This is either falsely documented or a bug -- see ...
Long-winded explanation of why some code is the way it is or various
other subtleties which might incite head-scratching and WTF'ing.
removed in 0.09, kill by ~0.25
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.