--- /dev/null
+
+# 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
projects / pkg-perl / blobdiff