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, 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 Create 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 In the following examples, F<parrot> contains the Parrot distribution, and
  32 F<workingdir> contains F<parrot>. The name F<workingdir> is just a placeholder
  33 for whatever the distribution's parent directory is called on your machine.
  34
  35     workingdir
  36         |
  37         +--> parrot
  38                 |
  39                 +--> LICENSE
  40                 |
  41                 +--> src
  42                 |
  43                 +--> tools
  44                 |
  45                 +--> ...
  46
  47 =over
  48
  49 =item C<svn>
  50
  51 If you are working with a checked out copy of parrot then please generate
  52 your patch with C<svn diff>.
  53
  54     cd parrot
  55     svn status
  56     svn diff > my_contribution.patch
  57
  58 =item Single C<diff>
  59
  60 If you are working from a released distribution of Parrot and the change you
  61 wish to make affects only one or two files, then you can supply a C<diff> for
  62 each file.  The C<diff> should be created in F<parrot>.  Please be sure to
  63 create a unified diff, with C<diff -u>.
  64
  65     cd parrot
  66     diff -u docs/submissions.pod docs/submissions.new > submissions.patch
  67
  68 Win32 users will probably need to specify C<-ub>.
  69
  70 =item Recursive C<diff>
  71
  72 If the change is more wide-ranging, then create an identical copy of F<parrot>
  73 in F<workingdir> and rename it F<parrot.new>. Modify F<parrot.new> and run a
  74 recursive C<diff> on the two directories to create your patch. The C<diff>
  75 should be created in F<workingdir>.
  76
  77     cd workingdir
  78     diff -ur --exclude='.svn' parrot parrot.new > docs.patch
  79
  80 Mac OS X users should also specify C<--exclude=.DS_Store>.
  81
  82 =item C<CREDITS>
  83
  84 Each and every patch is an important contribution to Parrot and it's important
  85 that these efforts are recognized.  To that end, the F<CREDITS> file contains
  86 an informal list of contributors and their contributions made to Parrot.  Patch
  87 submitters are encouraged to include a new or updated entry for themselves in
  88 F<CREDITS> as part of their patch.
  89
  90 The format for entries in F<CREDITS> is defined at the top of the file.
  91
  92 =back
  93
  94 =head1 How To Submit A Patch
  95
  96 =over 4
  97
  98 =item 1
  99
 100 Go to Parrot's ticket tracking system at
 101 L<https://trac.parrot.org/parrot/>. Log in, or create an account if you
 102 don't have one yet.
 103
 104 =item 2
 105
 106 If there is already a ticket for the bug or feature that your patch relates
 107 to, just attach the patch directly to the ticket.
 108
 109 =item 3
 110
 111 Otherwise select "New Ticket" at the top of the site.
 112 L<https://trac.parrot.org/parrot/newticket>
 113
 114 =item 4
 115
 116 Give a clear and concise Summary.  You do B<NOT> need to prefix the Summary
 117 with a C<[PATCH]> identifier.  Instead, in the lower-right corner of the
 118 F<newticket> page, select status C<new> in the F<Patch status> drop-down box.
 119
 120 =item 5
 121
 122 The Description should contain an explanation of the purpose of the patch, and
 123 a list of all files affected with summary of the changes made in each file.
 124 Optionally, the output of the C<diffstat(1)> utility when run on your patch(s)
 125 may be included at the bottom of the message body.
 126
 127 =item 6
 128
 129 Set the Type of the ticket to "patch". Set other relevant drop-down
 130 menus, such as Version (the version of Parrot where you encountered the
 131 problem), Platform, or Severity.  As mentioned above, select status C<new> in
 132 the F<Patch status> drop-down box.
 133
 134 =item 7
 135
 136 Check the box for "I have files to attach to this ticket". Double-check
 137 that you've actually done this, because it's easy to forget.
 138
 139 B<DO NOT> paste the patch file content into the Description.
 140
 141 =item 8
 142
 143 Click the "Create ticket" button. On the next page attach your patch
 144 file(s).
 145
 146 =back
 147
 148 =head1 Applying Patches
 149
 150 You may wish to apply a patch submitted by someone else before the patch is
 151 incorporated into SVN.
 152
 153 For single C<diff> patches or C<svn> patches, copy the patch file to
 154 F<parrot>, and run:
 155
 156     cd parrot
 157     patch -p0 < some.patch
 158
 159 For recursive C<diff> patches, copy the patch file to F<workingdir>, and run:
 160
 161     cd workingdir
 162     patch -p0 < some.patch
 163
 164 In order to be on the safe side run 'make test' before actually committing
 165 the changes.
 166
 167 =head2 Configuration of files to ignore
 168
 169 Sometimes new files will be created in the configuration and build process of
 170 Parrot. These files should not show up when checking the distribution with
 171
 172     svn status
 173
 174 or
 175
 176     perl tools/dev/manicheck.pl
 177
 178 The list of these ignore files can be set up with:
 179
 180     svn propedit svn:ignore <PATH>
 181
 182 In order to keep the two different checks synchronized,
 183 the MANIFEST and MANIFEST.SKIP file should be regenerated with:
 184
 185     perl tools/dev/mk_manifest_and_skip.pl
 186
 187
 188 =head1 How To Submit Something New
 189
 190 If you have a new feature to add to Parrot, such as a new test.
 191
 192 =over
 193
 194 =item 1
 195
 196 Add your new file path(s), relative to F<parrot>, to the file MANIFEST. Create
 197 a patch for the MANIFEST file according to the instructions in B<How To Submit
 198 A Patch>.
 199
 200 =item 2
 201
 202 If you have a new test script ending in C<.t>, some mailers may become confused
 203 and consider it an application/x-troff. One way around this (for *nix users) is
 204 to diff the file against /dev/null like this:
 205
 206     cd parrot
 207     diff -u /dev/null newfile.t > newfile.patch
 208
 209 =item 3
 210
 211 Go to Parrot's ticket tracking system at
 212 L<https://trac.parrot.org/parrot/>. Log in, or create an account if you
 213 don't have one yet.
 214
 215 =item 4
 216
 217 Select "New Ticket" L<https://trac.parrot.org/parrot/newticket>.
 218
 219 =item 5
 220
 221 Give a clear and concise Summary.
 222
 223 Prefix it with a C<[NEW]> identifier.
 224
 225 =item 6
 226
 227 The Description should contain an explanation of the purpose of the feature
 228 you are adding.  Optionally, include the output of the C<diffstat(1)> utility
 229 when run on your patch(es).
 230
 231 =item 7
 232
 233 Set the Type of the ticket to "patch". Set other relevant drop-down
 234 menus, such as Version, Platform, or Severity.
 235
 236 =item 8
 237
 238 Check the box for "I have files to attach to this ticket"
 239
 240 Double-check that you've actually done this, because it's easy to forget.
 241
 242 B<DO NOT> paste the content of the new file or files into the body of the
 243 message.
 244
 245 =item 9
 246
 247 Click the "Create ticket" button. On the next page attach the patch for
 248 MANIFEST and your new file(s).
 249
 250 =back
 251
 252 =head1 What Happens Next?
 253
 254 If you created a new ticket for the submission, you will be taken to the page
 255 for the new ticket and can check on the progress of your submission there.
 256 This identifier should be used in all correspondence concerning the submission.
 257
 258 Everyone on Trac sees the submission and can comment on it. A developer with
 259 SVN commit authority can commit it to SVN once it is clear that it is the
 260 right thing to do.
 261
 262 However developers with SVN commit authority may not commit your changes
 263 immediately if they are large or complex, as we need time for peer review.
 264
 265 A list of active tickets can be found here:
 266 L<http://trac.parrot.org/parrot/report/1>
 267
 268 A list of all the unresolved patches is at:
 269 L<http://trac.parrot.org/parrot/report/15>
 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
 306 request in 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