---
name: "Test::HACKING"
section: "3pm"
platform: "linux"
package: "libtest-harness-perl"
version: "3.50-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test::HACKING"
---

# Test::HACKING(3pm)

contributing to TAP::Harness

## NAME

HACKING.pod - contributing to TAP::Harness

## ABOUT

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

If you are looking for more information on how to *use* TAP::Harness, you probably want \<http://testanything.org/testing-with-tap/perl/tap-parser-cookbook.html\> instead.

## Getting Started

See the resources section in *META.yml* or *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:

```
  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.

## Formatting

### perltidy

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 editor:

- •

  vim

  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.

- •

  emacs

  For emacs, you can use this snippet from Sam Tregar (\<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)
  ```

## Tests and Coverage

...

## Writing for Compatibility

...

## Use TAP::Object

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

## Exception Handling

Exceptions should be raised with Carp:

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

## Deprecation cycle

Any *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. Carp a suitable message
  3. Release
  4. Change the code
  5. Release
```

## Documentation

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.

### Pod Commands

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.

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

- "=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, `$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 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.

### Pod Formatting Codes

- L\<Some::Module\>

  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 "`"<Some::Module|Some::Module>"`".

### VERSION

The version numbers are updated by Perl::Version.

### DEVELOPER DOCS/NOTES

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

- 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 ...
  ```

- 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
  ```

- deprecated

  ```
    =for deprecated
      removed in 0.09, kill by ~0.25
  ```

## 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.