# Copyright (C) 2004-2007, The Perl Foundation.
# $Id: submissions.pod 17926 2007-04-01 10:11:12Z bernhard $

=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.
This sanity checking can be done by running '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
                |
                +--> LICENSES
                |
                +--> src 
                |
                +--> tools
                |
                +--> ...

=over

=item Single C<diff>

If the change you wish to make is small it will generally affect only one or
two files, in which case supply a C<diff> for each file. The C<diff> should be
created in F<parrot>.

    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

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

=item C<svn>

Patches for a single and multiple files can also be generated by svn.
This is the recommended way.

    cd parrot
    svn diff > docs.patch

=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 to be ignored files

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 above 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, 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 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 those developers with SVN commit authority stick to this scheme for all
but the most trivial of their own patches, to allow time for peer review of
their changes.

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 generated and can be viewed here
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 one or more patches via the process described in this document that are
accepted.

=item 2

Obtain a perl.org account at https://auth.perl.org/auth/account

=item 3

The pumpkin or architect must put in a request to have your perl.org account 
granted svn commit privileges.

The two best ways to let us know you're interested in becoming a committer
are via the parrot-porters mailing list, or via IRC (#parrot on irc.perl.org).
Thanks for your help!

=back

=head1 HISTORY

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

=cut