# Copyright (C) 2004-2008, The Perl Foundation.
# $Id: /mirror/trunk/docs/submissions.pod 32588 2008-11-11T21:20:52.510180Z particle  $

=head1 NAME

docs/submissions.pod - Parrot Submission Instructions

=head1 ABSTRACT

How to submit bug reports, patches and new files to Parrot.

=head1 How To Submit A Bug Report

If you encounter an error while working with Parrot, and don't understand what
is causing it, then submit a bug report using the F<parrotbug> utility. The
simplest way to use it is to run

    % ./parrotbug

in the distribution's root directory, and follow the prompts.

However, if you do know how to fix the problem you encountered, then think
about submitting a patch, or (see below) getting commit privileges.

=head1 How To Submit A Patch

Try to keep your patches specific to a single change, and ensure that your
change does not break any tests.  Do this by running C<make test>.  If there is
no test for the fixed bug, please provide one.

=over

=item 1

Create the patch.

In the following examples, F<parrot> contains the Parrot distribution, and
F<workingdir> contains F<parrot>. The name F<workingdir> is just a placeholder
for whatever the distribution's parent directory is called on your machine.

    workingdir
        |
        +--> parrot
                |
                +--> LICENSE
                |
                +--> src
                |
                +--> tools
                |
                +--> ...

=over

=item C<svn>

If you are working with a checked out copy of parrot then please generate
your patch with C<svn diff>.

    cd parrot
    svn status
    svn diff > my_contribution.patch

=item Single C<diff>

If you are working from a released distribution of Parrot and the change you
wish to make affects only one or two files, then you can supply a C<diff> for
each file.  The C<diff> should be created in F<parrot>.  Please be sure to
create a unified diff, with C<diff -u>.

    cd parrot
    diff -u docs/submissions.pod docs/submissions.new > submissions.patch

Win32 users will probably need to specify C<-ub>.

=item Recursive C<diff>

If the change is more wide-ranging, then create an identical copy of F<parrot>
in F<workingdir> and rename it F<parrot.new>. Modify F<parrot.new> and run a
recursive C<diff> on the two directories to create your patch. The C<diff>
should be created in F<workingdir>.

    cd workingdir
    diff -ur --exclude='.svn' parrot parrot.new > docs.patch

Mac OS X users should also specify C<--exclude=.DS_Store>.

=item C<CREDITS>

Each and every patch is an important contribution to Parrot and it's important
that these efforts are recognized.  To that end, the F<CREDITS> file contains
an informal list of contributors and their contributions made to Parrot.  Patch
submitters are encouraged to include a new or updated entry for themselves in
F<CREDITS> as part of their patch.

The format for entries in F<CREDITS> is defined at the top of the file.

=back

=item 2

Create a plain text email.

=item 3

Set the recipient to B<parrotbug> I<at> B<parrotcode> I<dot> B<org>.

=item 4

Give the message a clear and concise subject.

Prefix it with a C<[PATCH]> identifier.

=item 5

The message body should contain an explanation of the purpose of the patch, and
a list of all files affected with summary of the changes made in each file.
Optionally, the output of the C<diffstat(1)> utility when run on your patch(s)
may be included at the bottom of the message body.

=item 6

Attach the patch file(s).

Double-check that you've actually done this, because it's easy to forget.

B<DO NOT> paste the patch file content into the body of the message.

=item 7

Send the mail.

=back

=head1 Applying Patches

You may wish to apply a patch submitted by someone else before the patch is
incorporated into SVN.

For single C<diff> patches or C<svn> patches, copy the patch file to
F<parrot>, and run:

    cd parrot
    patch -p0 < some.patch

For recursive C<diff> patches, copy the patch file to F<workingdir>, and run:

    cd workingdir
    patch -p0 < some.patch

In order to be on the safe side run 'make test' before actually committing
the changes.

=head2 Configuration of files to ignore

Sometimes new files will be created in the configuration and build process of
Parrot. These files should not show up when checking the distribution with

    svn status

or

    perl tools/dev/manicheck.pl

The list of these ignore files can be set up with:

    svn propedit svn:ignore <PATH>

In order to keep the two different checks synchronized,
the MANIFEST and MANIFEST.SKIP file should be regenerated with:

    perl tools/dev/mk_manifest_and_skip.pl


=head1 How To Submit Something New

If you have a new feature to add to Parrot, such as a new test.

=over

=item 1

Add your new file path(s), relative to F<parrot>, to the file MANIFEST. Create
a patch for the MANIFEST file according to the instructions in B<How To Submit
A Patch>.

=item 2

If you have a new test script ending in C<.t>, some mailers may become confused
and consider it an application/x-troff. One way around this (for *nix users) is
to diff the file against /dev/null like this:

    cd parrot
    diff -u /dev/null newfile.t > newfile.patch

=item 3

Create a plain text email.

=item 4

Set the recipient to B<parrotbug> I<at> B<parrotcode> I<dot> B<org>.

=item 5

Give the message a clear and concise subject.

Prefix it with a C<[NEW]> identifier.

=item 6

The message body should contain an explanation of the purpose of the feature
you are adding.  Optionally, include the output of the C<diffstat(1)> utility
when run on your patch(es).

=item 7

Attach the patch for MANIFEST and your new file(s).

Double-check that you've actually done this, because it's easy to forget.

B<DO NOT> paste the content of the new file or files into the body of the
message.

=item 8

Send the mail.

=back

=head1 What Happens Next?

RT creates a ticket for the submission, and you will receive an automatic reply
with details of the ticket identifier. This identifier should be used in all
further correspondence concerning the submission.

Everyone on the list sees the submission, and can comment on it. A developer
with SVN commit authority will commit it to SVN once it is clear that it is the
right thing to do.

Even developers with SVN commit authority stick to this scheme for larger or
more complex changes, to allow time for peer review.

You can check the progress of your submission at the Parrot bugs page
L<http://bugs6.perl.org/>. If you have trouble logging in try username C<guest>
with password C<guest>.

A Parrot Bug Summary page is also available from
L<https://rt.perl.org/rt3/NoAuth/parrot/Overview.html>

A list of all the unresolved patches is at
L<http://www.parrotcode.org/openpatches.html>

=head1 Patches for the Parrot website

The sources for L<http://www.parrotcode.org> are managed in a subversion
repository. The repository can be fetched from
https://svn.perl.org/perl.org/docs/live/parrotcode/. A read only copy can be
retrieved with 'guest/guest'.

You will notice that some of the content is generated directly from the Parrot
repository. So the usual rules for Parrot patches apply for this content.

For changes specific for parrotcode.org please send patches to B<webmaster>
I<at> B<perl> I<dot> B<org>, and cc B<parrot-porters> I<at> B<perl> I<dot>
B<org>.

=head1 Getting Commit Privileges

If you are interested in getting commit privileges to Parrot, here is
the procedure:

=over 4

=item 1

Submit several high quality patches (and have them committed) via the process
described in this document.  This process may take weeks or months.

=item 2

Obtain a perl.org account at L<https://auth.perl.org/auth/account>

=item 3

Submit a Perl Contributor License Agreement; this document signifies that you
have the authority to license your work to The Perl Foundation for inclusion in
their projects.  You may need to discuss this with your employer if you
contribute to Parrot on work time or with work resources, or depending on your
employment agreement.

L<http://www.perlfoundation.org/contributor_license_agreement>

=item 4

Request commit access via the C<parrot-porters> mailing list, or via IRC
(#parrot on irc.perl.org).  The existing commiters will discuss your request in
the next couple of weeks.

If approved, a metacommiter will update the permissions to allow you to commit
to Parrot; see C<RESPONSIBLE_PARTIES> for the current list.  Welcome aboard!

=back

Thanks for your help!

=head1 HISTORY

Adapted by Michael Scott from a tutorial submitted by Aldo Calpini, with some
additional remarks from Bruce Gray.

=cut
