AnonymousFox

//usr/share/man/man3/Test::HACKING.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "HACKING 3"
.TH HACKING 3 "2015-04-17" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HACKING.pod \- contributing to TAP::Harness
.SH "ABOUT"
.IX Header "ABOUT"
This is the guide for TAP::Harness internals contributors (developers,
testers, documenters.)
.PP
If you are looking for more information on how to \fIuse\fR TAP::Harness,
you probably want
<http://testanything.org/testing\-with\-tap/perl/tap::parser\-cookbook.html>
instead.
.SH "Getting Started"
.IX Header "Getting Started"
See the resources section in \fI\s-1META\s0.yml\fR or \fIBuild.PL\fR for links to the
project mailing list, bug tracker, svn repository, etc.
.PP
For ease of reference, at the time of writing the \s-1SVN\s0 repository was at:
.PP
.Vb 1
\&  http://svn.hexten.net/tapx
.Ve
.PP
To get the latest version of trunk:
.PP
.Vb 1
\&  git clone git://github.com/Perl\-Toolchain\-Gang/Test\-Harness.git
.Ve
.PP
For best results, read the rest of this file, check \s-1RT\s0 for bugs which
scratch your itch, join the mailing list, etc.
.SH "Formatting"
.IX Header "Formatting"
.SS "perltidy"
.IX Subsection "perltidy"
The project comes with a \f(CW\*(C`.perltidyrc\*(C'\fR, 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:
.IP "\(bu" 4
vim
.Sp
In \f(CW\*(C`.vimrc\*(C'\fR, you can add the following lines:
.Sp
.Vb 2
\& nnoremap <Leader>pt :%!perltidy \-q<cr> " only work in \*(Aqnormal\*(Aq mode
\& vnoremap <Leader>pt :!perltidy \-q<cr>  " only work in \*(Aqvisual\*(Aq mode
.Ve
.Sp
In other words, if your \f(CW\*(C`Leader\*(C'\fR is a backslash, you can type \f(CW\*(C`\ept\*(C'\fR to
reformat the file using the \f(CW\*(C`.perltidyrc\*(C'\fR.  If you are in visual mode
(selecting lines with shift-v), then only the code you have currently have
selected will be reformatted.
.IP "\(bu" 4
emacs
.Sp
For emacs, you can use this snippet from Sam Tregar
(<http://use.perl.org/~samtregar/journal/30185>):
.Sp
.Vb 6
\& (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 "\eM\-t" \`perltidy\-region)
\& (global\-set\-key "\eM\-T" \`perltidy\-all)
.Ve
.SH "Tests and Coverage"
.IX Header "Tests and Coverage"
\&...
.SH "Writing for Compatibility"
.IX Header "Writing for Compatibility"
\&...
.SH "Use TAP::Object"
.IX Header "Use TAP::Object"
TAP::Object is the common base class to all TAP::* modules, and should be for
any that you write.
.SH "Exception Handling"
.IX Header "Exception Handling"
Exceptions should be raised with Carp:
.PP
.Vb 2
\&  require Carp;
\&  Carp::croak("Unsupported syntax version: $version");
\&
\&  require Carp;
\&  Carp::confess("Unsupported syntax version: $version");
.Ve
.SH "Deprecation cycle"
.IX Header "Deprecation cycle"
Any \fIdocumented\fR 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:
.PP
.Vb 5
\&  1. Document the deprecation
\&  2. Carp a suitable message
\&  3. Release
\&  4. Change the code
\&  5. Release
.Ve
.SH "Documentation"
.IX Header "Documentation"
The end-user and \s-1API\s0 documentation is all in the 'lib/' directory.  In
\&.pm files, the pod is \*(L"inline\*(R" to the code.  See perlpod for more
about pod.
.SS "Pod Commands"
.IX Subsection "Pod Commands"
For compatibility's sake, we do not use the =head3 and =head4 commands.
.ie n .IP """=head1 SECTION""" 4
.el .IP "\f(CW=head1 SECTION\fR" 4
.IX Item "=head1 SECTION"
Sections begin with an \f(CW\*(C`=head1\*(C'\fR command and are all-caps.
.Sp
.Vb 8
\&  NAME
\&  VERSION
\&  SYNOPSIS
\&  CONSTRUCTOR
\&  METHODS
\&  CLASS METHODS
\&  SOME OTHER SORT OF METHODS
\&  SEE ALSO
.Ve
.ie n .IP """=head2 method""" 4
.el .IP "\f(CW=head2 method\fR" 4
.IX Item "=head2 method"
The \f(CW\*(C`=head2\*(C'\fR command documents a method.  The name of the method should have no adornment (e.g. don't C<method> or C<method($list, \f(CW$of\fR, \f(CW$params\fR)>.)
.Sp
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).
.Sp
.Vb 1
\&  =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) {
\&      ...
\&    }
.Ve
.ie n .IP """=item parameter""" 4
.el .IP "\f(CW=item parameter\fR" 4
.IX Item "=item parameter"
Use \f(CW\*(C`=item\*(C'\fR commands for method arguments and parameters (and etc.)  In
most html pod formatters, these \fIdo not\fR get added to the
table-of-contents at the top of the page.
.SS "Pod Formatting Codes"
.IX Subsection "Pod Formatting Codes"
.IP "L<Some::Module>" 4
.IX Item "L<Some::Module>"
Be careful of the wording of \f(CW\*(C`L<Some::Module>\*(C'\fR.  Older pod
formatters would render this as \*(L"the Some::Module manpage\*(R", so it is
best to either word your links as "\f(CW\*(C`(see <Some::Module> for
details.)\*(C'\fR\*(L" or use the \*(R"explicit rendering\*(L" form of
\&\*(R"\f(CW\*(C`<Some::Module|Some::Module>\*(C'\fR".
.SS "\s-1VERSION\s0"
.IX Subsection "VERSION"
The version numbers are updated by Perl::Version.
.SS "\s-1DEVELOPER\s0 \s-1DOCS/NOTES\s0"
.IX Subsection "DEVELOPER DOCS/NOTES"
The following \*(L"formats\*(R" are used with \f(CW\*(C`=begin\*(C'\fR/\f(CW\*(C`=end\*(C'\fR and \f(CW\*(C`=for\*(C'\fR
commands for pod which is not part of the public end\-user/API
documentation.
.IP "note" 4
.IX Item "note"
Use this if you are uncertain about a change to some pod or think it
needs work.
.Sp
.Vb 1
\&  =head2 some_method
\&
\&    ...
\&
\&  =for note
\&    This is either falsely documented or a bug \-\- see ...
.Ve
.IP "developer" 4
.IX Item "developer"
.Vb 1
\&  =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\*(Aqing.
\&
\&  =end developer
.Ve
.IP "deprecated" 4
.IX Item "deprecated"
.Vb 2
\&  =for deprecated
\&    removed in 0.09, kill by ~0.25
.Ve
.SH "Committing to Subversion"
.IX Header "Committing to Subversion"
If you have commit access, please bear this in mind.
.PP
Development is done either on trunk or a branch, as appropriate:
.PP
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.
.PP
If in doubt discuss it on the mailing list before you commit.