docs/submissions.pod

   1 # Copyright (C) 2004-2008, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/submissions.pod - Parrot Submission Instructions
   7
   8 =head1 ABSTRACT
   9
  10 How to submit bug reports, patches and new files to Parrot.
  11
  12 =head1 How To Submit A Bug Report
  13
  14 If you encounter an error while working with Parrot, and don't understand what
  15 is causing it, then create a bug report using the F<parrotbug> utility. The
  16 simplest way to use it is to run
  17
  18     % ./parrotbug
  19
  20 in the distribution's root directory, and follow the prompts.
  21
  22 However, if you do know how to fix the problem you encountered, then think
  23 about submitting a patch, or (see below) getting commit privileges.
  24
  25 =head1 How To Submit A Patch
  26
  27 Try to keep your patches specific to a single change, and ensure that your
  28 change does not break any tests.  Do this by running C<make test>.  If there is
  29 no test for the fixed bug, please provide one.
  30
  31 =over
  32
  33 =item 1
  34
  35 Create the patch.
  36
  37 In the following examples, F<parrot> contains the Parrot distribution, and
  38 F<workingdir> contains F<parrot>. The name F<workingdir> is just a placeholder
  39 for whatever the distribution's parent directory is called on your machine.
  40
  41     workingdir
  42         |
  43         +--> parrot
  44                 |
  45                 +--> LICENSE
  46                 |
  47                 +--> src
  48                 |
  49                 +--> tools
  50                 |
  51                 +--> ...
  52
  53 =over
  54
  55 =item C<svn>
  56
  57 If you are working with a checked out copy of parrot then please generate
  58 your patch with C<svn diff>.
  59
  60     cd parrot
  61     svn status
  62     svn diff > my_contribution.patch
  63
  64 =item Single C<diff>
  65
  66 If you are working from a released distribution of Parrot and the change you
  67 wish to make affects only one or two files, then you can supply a C<diff> for
  68 each file.  The C<diff> should be created in F<parrot>.  Please be sure to
  69 create a unified diff, with C<diff -u>.
  70
  71     cd parrot
  72     diff -u docs/submissions.pod docs/submissions.new > submissions.patch
  73
  74 Win32 users will probably need to specify C<-ub>.
  75
  76 =item Recursive C<diff>
  77
  78 If the change is more wide-ranging, then create an identical copy of F<parrot>
  79 in F<workingdir> and rename it F<parrot.new>. Modify F<parrot.new> and run a
  80 recursive C<diff> on the two directories to create your patch. The C<diff>
  81 should be created in F<workingdir>.
  82
  83     cd workingdir
  84     diff -ur --exclude='.svn' parrot parrot.new > docs.patch
  85
  86 Mac OS X users should also specify C<--exclude=.DS_Store>.
  87
  88 =item C<CREDITS>
  89
  90 Each and every patch is an important contribution to Parrot and it's important
  91 that these efforts are recognized.  To that end, the F<CREDITS> file contains
  92 an informal list of contributors and their contributions made to Parrot.  Patch
  93 submitters are encouraged to include a new or updated entry for themselves in
  94 F<CREDITS> as part of their patch.
  95
  96 The format for entries in F<CREDITS> is defined at the top of the file.
  97
  98 =back
  99
 100 =item 2
 101
 102 Go to Parrot's ticket tracking system at
 103 L<https://trac.parrot.org/parrot/>. Log in, or create an account if you
 104 don't have one yet.
 105
 106 =item 3
 107
 108 Select "New Ticket" L<https://trac.parrot.org/parrot/newticket>.
 109
 110 =item 4
 111
 112 Give a clear and concise Summary.
 113
 114 Prefix it with a C<[PATCH]> identifier.
 115
 116 =item 5
 117
 118 The Description should contain an explanation of the purpose of the patch, and
 119 a list of all files affected with summary of the changes made in each file.
 120 Optionally, the output of the C<diffstat(1)> utility when run on your patch(s)
 121 may be included at the bottom of the message body.
 122
 123 =item 6
 124
 125 Set the Type of the ticket to "patch". Set other relevant drop-down
 126 menus, such as Version (the version of Parrot where you encountered the
 127 problem), Platform, or Severity.
 128
 129 =item 7
 130
 131 Check the box for "I have files to attach to this ticket"
 132
 133 Double-check that you've actually done this, because it's easy to forget.
 134
 135 B<DO NOT> paste the patch file content into the Description.
 136
 137 =item 8
 138
 139 Click the "Create ticket" button. On the next page attach your patch
 140 file(s).
 141
 142 =back
 143
 144 =head1 Applying Patches
 145
 146 You may wish to apply a patch submitted by someone else before the patch is
 147 incorporated into SVN.
 148
 149 For single C<diff> patches or C<svn> patches, copy the patch file to
 150 F<parrot>, and run:
 151
 152     cd parrot
 153     patch -p0 < some.patch
 154
 155 For recursive C<diff> patches, copy the patch file to F<workingdir>, and run:
 156
 157     cd workingdir
 158     patch -p0 < some.patch
 159
 160 In order to be on the safe side run 'make test' before actually committing
 161 the changes.
 162
 163 =head2 Configuration of files to ignore
 164
 165 Sometimes new files will be created in the configuration and build process of
 166 Parrot. These files should not show up when checking the distribution with
 167
 168     svn status
 169
 170 or
 171
 172     perl tools/dev/manicheck.pl
 173
 174 The list of these ignore files can be set up with:
 175
 176     svn propedit svn:ignore <PATH>
 177
 178 In order to keep the two different checks synchronized,
 179 the MANIFEST and MANIFEST.SKIP file should be regenerated with:
 180
 181     perl tools/dev/mk_manifest_and_skip.pl
 182
 183
 184 =head1 How To Submit Something New
 185
 186 If you have a new feature to add to Parrot, such as a new test.
 187
 188 =over
 189
 190 =item 1
 191
 192 Add your new file path(s), relative to F<parrot>, to the file MANIFEST. Create
 193 a patch for the MANIFEST file according to the instructions in B<How To Submit
 194 A Patch>.
 195
 196 =item 2
 197
 198 If you have a new test script ending in C<.t>, some mailers may become confused
 199 and consider it an application/x-troff. One way around this (for *nix users) is
 200 to diff the file against /dev/null like this:
 201
 202     cd parrot
 203     diff -u /dev/null newfile.t > newfile.patch
 204
 205 =item 3
 206
 207 Go to Parrot's ticket tracking system at
 208 L<https://trac.parrot.org/parrot/>. Log in, or create an account if you
 209 don't have one yet.
 210
 211 =item 4
 212
 213 Select "New Ticket" L<https://trac.parrot.org/parrot/newticket>.
 214
 215 =item 5
 216
 217 Give a clear and concise Summary.
 218
 219 Prefix it with a C<[NEW]> identifier.
 220
 221 =item 6
 222
 223 The Description should contain an explanation of the purpose of the feature
 224 you are adding.  Optionally, include the output of the C<diffstat(1)> utility
 225 when run on your patch(es).
 226
 227 =item 7
 228
 229 Set the Type of the ticket to "patch". Set other relevant drop-down
 230 menus, such as Version, Platform, or Severity.
 231
 232 =item 8
 233
 234 Check the box for "I have files to attach to this ticket"
 235
 236 Double-check that you've actually done this, because it's easy to forget.
 237
 238 B<DO NOT> paste the content of the new file or files into the body of the
 239 message.
 240
 241 =item 9
 242
 243 Click the "Create ticket" button. On the next page attach the patch for
 244 MANIFEST and your new file(s).
 245
 246 =back
 247
 248 =head1 What Happens Next?
 249
 250 Trac creates a ticket for the submission, and you will receive an automatic reply
 251 with details of the ticket identifier. This identifier should be used in all
 252 further correspondence concerning the submission.
 253
 254 Everyone on the list sees the submission, and can comment on it. A developer
 255 with SVN commit authority will commit it to SVN once it is clear that it is the
 256 right thing to do.
 257
 258 Even developers with SVN commit authority stick to this scheme for larger or
 259 more complex changes, to allow time for peer review.
 260
 261 You can check the progress of your submission at the Parrot bugs page
 262 L<http://bugs6.perl.org/>. If you have trouble logging in try username C<guest>
 263 with password C<guest>.
 264
 265 A Parrot Bug Summary page is also available from
 266 L<https://rt.perl.org/rt3/NoAuth/parrot/Overview.html>
 267
 268 A list of all the unresolved patches is at
 269 L<http://www.parrotcode.org/openpatches.html>
 270
 271 =head1 Patches for the Parrot website
 272
 273 The L<http://www.parrot.org> website is hosted in a Drupal CMS. Submit
 274 changes through the usual ticket interface in Trac.
 275
 276 =head1 Getting Commit Privileges
 277
 278 If you are interested in getting commit privileges to Parrot, here is
 279 the procedure:
 280
 281 =over 4
 282
 283 =item 1
 284
 285 Submit several high quality patches (and have them committed) via the process
 286 described in this document.  This process may take weeks or months.
 287
 288 =item 2
 289
 290 Obtain a Trac account at L<https://trac.parrot.org/parrot>
 291
 292 =item 3
 293
 294 Submit a Parrot Contributor License Agreement; this document signifies that you
 295 have the authority to license your work to Parrot Foundation for inclusion in
 296 their projects.  You may need to discuss this with your employer if you
 297 contribute to Parrot on work time or with work resources, or depending on your
 298 employment agreement.
 299
 300 L<http://www.parrot.org/files/parrot_cla.pdf>
 301
 302 =item 4
 303
 304 Request commit access via the C<parrot-dev> mailing list, or via IRC
 305 (#parrot on irc.parrot.org).  The existing committers will discuss your request in
 306 the next couple of weeks.
 307
 308 If approved, a metacommitter will update the permissions to allow you to commit
 309 to Parrot; see C<RESPONSIBLE_PARTIES> for the current list.  Welcome aboard!
 310
 311 =back
 312
 313 Thanks for your help!
 314
 315 =cut