git.maemo.org Git - pkg-perl/blob - deb-src/libtest-harness-perl/libtest-harness-perl-3.12/HACKING.pod

   1
   2 # this is in pod format (try `perldoc HACKING.pod`)
   3
   4 =pod
   5
   6 =head1 NAME
   7
   8 HACKING.pod - contributing to TAP::Harness
   9
  10 =head1 ABOUT
  11
  12 This is the guide for TAP::Harness internals contributors (developers,
  13 testers, documenters.)
  14
  15 If you are looking for more information on how to I<use> TAP::Harness,
  16 you probably want
  17 L<http://testanything.org/wiki/index.php/TAP::Parser_Cookbook> instead.
  18
  19 =head1 Getting Started
  20
  21 See the resources section in I<META.yml> or I<Build.PL> for links to the
  22 project mailing list, bug tracker, svn repository, etc.
  23
  24 For ease of reference, at the time of writing the SVN repository was at:
  25
  26   http://svn.hexten.net/tapx
  27
  28 To get the latest version of trunk:
  29
  30   svn co http://svn.hexten.net/tapx/trunk
  31
  32 For best results, read the rest of this file, check RT for bugs which
  33 scratch your itch, join the mailing list, etc.
  34
  35 =head1 Formatting
  36
  37 =head2 perltidy
  38
  39 The project comes with a C<.perltidyrc>, which perltidy will
  40 automatically use if the project root is your working directory.  This
  41 is setup by default to read and write the perl code on a pipe.  To
  42 configure your editor:
  43
  44 =over 4
  45
  46 =item * vim
  47
  48 In C<.vimrc>, you can add the following lines:
  49
  50  nnoremap <Leader>pt :%!perltidy -q<cr> " only work in 'normal' mode
  51  vnoremap <Leader>pt :!perltidy -q<cr>  " only work in 'visual' mode
  52
  53 In other words, if your C<Leader> is a backslash, you can type C<\pt> to
  54 reformat the file using the C<.perltidyrc>.  If you are in visual mode
  55 (selecting lines with shift-v), then only the code you have currently have
  56 selected will be reformattted.
  57
  58 =item * emacs
  59
  60 For emacs, you can use this snippet from Sam Tregar
  61 (L<http://use.perl.org/~samtregar/journal/30185>):
  62
  63  (defun perltidy-region ()
  64     "Run perltidy on the current region."
  65     (interactive)
  66     (save-excursion
  67       (shell-command-on-region (point) (mark) "perltidy -q" nil t)
  68       (cperl-mode)))
  69
  70  (defun perltidy-all ()
  71     "Run perltidy on the current region."
  72     (interactive)
  73     (let ((p (point)))
  74       (save-excursion
  75         (shell-command-on-region (point-min) (point-max) "perltidy -q" nil t)
  76         )
  77       (goto-char p)
  78       (cperl-mode)))
  79
  80  (global-set-key "\M-t" `perltidy-region)
  81  (global-set-key "\M-T" `perltidy-all)
  82
  83 =back
  84
  85 =head1 Tests and Coverage
  86
  87 ...
  88
  89 =for eric_not_it
  90   TODO link to a good guide on writing tests for TAP::Parser
  91
  92 =head1 Writing for Compatibility
  93
  94 ...
  95
  96 =for eric_not_it
  97   TODO explain no bundling, PERL_CORE, etc
  98
  99 =head1 Use TAP::Object
 100
 101 TAP::Object is the common base class to all TAP::* modules, and should be for
 102 any that you write.
 103
 104 =head1 Exception Handling
 105
 106 Exceptions should be raised with L<Carp>:
 107
 108   require Carp;
 109   Carp::croak("Unsupported syntax version: $version");
 110
 111   require Carp;
 112   Carp::confess("Unsupported syntax version: $version");
 113
 114 =head1 Deprecation cycle
 115
 116 Any I<documented> sub that needs to be changed or removed (and would therefore
 117 cause a backwards-compat issue) must go through a deprecation cycle to give
 118 developers a chance to adjust:
 119
 120   1. Document the deprecation
 121   2. Release
 122   3. Change the code
 123   4. Release
 124
 125 =head1 Documentation
 126
 127 The end-user and API documentation is all in the 'lib/' directory.  In
 128 .pm files, the pod is "inline" to the code.  See L<perlpod> for more
 129 about pod.
 130
 131 =head2 Pod Commands
 132
 133 For compatibility's sake, we do not use the =head3 and =head4 commands.
 134
 135 =over
 136
 137 =item C<=head1 SECTION>
 138
 139 Sections begin with an C<=head1> command and are all-caps.
 140
 141 =for eric_not_it
 142   I guess... Mixed case messes with various pod hacking tools.
 143
 144   NAME
 145   VERSION
 146   SYNOPSIS
 147   CONSTRUCTOR
 148   METHODS
 149   CLASS METHODS
 150   SOME OTHER SORT OF METHODS
 151   SEE ALSO
 152
 153 =item C<=head2 method>
 154
 155 =for eric_not_it
 156   The following is how I would do it, but opposite of what we have.
 157
 158 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)>.)
 159
 160 These sections should begin with a short description of what the method
 161 does, followed by one or more examples of usage.  If needed, elaborate
 162 on the subtleties of the parameters and context after (and/or between)
 163 the example(s).
 164
 165   =head2 this_method
 166
 167   This method does some blah blah blah.
 168
 169     my @answer = $thing->this_method(@arguments);
 170
 171   =head2 that_thing
 172
 173   Returns true if the thing is true.
 174
 175     if($thing->that_thing) {
 176       ...
 177     }
 178
 179 =item C<=item parameter>
 180
 181 Use C<=item> commands for method arguments and parameters (and etc.)  In
 182 most html pod formatters, these I<do not> get added to the
 183 table-of-contents at the top of the page.
 184
 185 =back
 186
 187 =head2 Pod Formatting Codes
 188
 189 =over
 190
 191 =item LE<lt>Some::Module>
 192
 193 Be careful of the wording of C<LE<lt>Some::ModuleE<gt>>.  Older pod
 194 formatters would render this as "the Some::Module manpage", so it is
 195 best to either word your links as "C<(see E<lt>Some::ModuleE<gt> for
 196 details.)>" or use the "explicit rendering" form of
 197 "C<E<lt>Some::Module|Some::ModuleE<gt>>".
 198
 199 =back
 200
 201 =head2 VERSION
 202
 203 The version numbers are updated by L<Perl::Version>.
 204
 205 =head2 DEVELOPER DOCS/NOTES
 206
 207 The following "formats" are used with C<=begin>/C<=end> and C<=for>
 208 commands for pod which is not part of the public end-user/API
 209 documentation.
 210
 211 =over
 212
 213 =item note
 214
 215 Use this if you are uncertain about a change to some pod or think it
 216 needs work.
 217
 218   =head2 some_method
 219
 220     ...
 221
 222   =for note
 223     This is either falsely documented or a bug -- see ...
 224
 225 =item developer
 226
 227   =begin developer
 228
 229   Long-winded explanation of why some code is the way it is or various
 230   other subtleties which might incite head-scratching and WTF'ing.
 231
 232   =end developer
 233
 234 =item deprecated
 235
 236   =for deprecated
 237     removed in 0.09, kill by ~0.25
 238
 239 =back
 240
 241 =head1 Committing to Subversion
 242
 243 If you have commit access, please bear this in mind.
 244
 245 Development is done either on trunk or a branch, as appropriate:
 246
 247 If it's something that might be controversial, break the build or take a long
 248 time (more than a couple of weeks) to complete then it'd probably be
 249 appropriate to branch. Otherwise it can go in trunk.
 250
 251 If in doubt discuss it on the mailing list before you commit.
 252
 253 =cut
 254
 255 =for developer
 256 ... or whatever.  I'm just making stuff up here.  If any of this is
 257 wrong, please correct it.  To the extent that there is an "official
 258 policy", it should be written down. --Eric
 259
 260 =cut
 261
 262 # vim:ts=2:sw=2:et:sta