# Copyright (C) 2004-2012, Parrot Foundation.

=pod

=head1 NAME

docs/submissions.pod - Parrot Submission Instructions

=head1 DESCRIPTION

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, create 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.

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

=head1 A NOTE ON RANDOM FAILURES

If you encounter errors that appear intermittently, it may be difficult or
impossible for Parrot developers to diagnose and solve the problem. It is
therefore recommended to control the sources of randomness in Parrot in an
attempt to eliminate the intermittency of the bug. There are three common
sources of randomness that should be considered.

=over

=item Pseudo-Random Number Generator

Direct use of a PRNG from within Parrot programs will lead to inconsistent
results. If possible, isolate the bug from PRNG use, for example, by logging
the random values which trigger the error and then hard coding them.

=item Address Space Layout Randomization

Several operating systems provide a security measure known as address space
layout randomization. In bugs involving stray pointers, this can cause
corruption in random Parrot subsystems. Temporarily disabling this feature may
make this problem consistent and therefore debugable.

=item Hash Seed

Parrot's hash implementation uses randomization of its seed as a precaution
against attacks based on hash collisions. The seed used can be directly
controlled using C<parrot>'s C<--hash-seed> parameter. To determine what seeds
are causing the error, Parrot can be rebuilt with C<DEBUG_HASH_SEED> set to
C<1>, which will cause C<parrot> to output the hash seed being used on every
invocation.

=back

=head1 HOW TO CREATE 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.

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<git>

If you are working with a git repository of parrot then please submit your
patch as a pull request on github. You can find instructions at
L<http://help.github.com/send-pull-requests/>

=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='.git' 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

=head1 HOW TO SUBMIT A PATCH

The preferrred method to submit matches to Parrot is as pull requests via
github. Please follow the instructions at
L<http://help.github.com/send-pull-requests/>.

=head1 APPLYING PATCHES

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

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

    cd parrot
    git apply some.patch

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

    cd workingdir
    git apply 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

    git status

or

    perl tools/dev/manicheck.pl

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 WHAT HAPPENS NEXT?

If you created a new issue, you will be taken to the issue page and can
check on the progress of discussion there.  The issue number should be
used in all out-of-band correspondence concerning the issue (e.g., in
email to the C<parrot-dev> mailing list).  Otherwise, everyone on the
parrot project can see the issue and can comment on it.

A developer with git commit privileges can merge your changes into the
main parrot repository, once it is clear that this is the right thing to
do.  However your pull request may not be processed right away if the
changes are large or complex, as we need time for peer review.

A list of open issues can be found here:
L<https://github.com/parrot/parrot/issues?state=open>

=head1 PATCHES FOR THE PARROT WEBSITE

The L<http://www.parrot.org> website is hosted in a Drupal CMS. Submit
changes through the usual ticket interface in Trac.

=head1 GETTING COMMIT PRIVILEGES

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

=over 4

=item 1

Obtain a github account at L<http://github.com>

=item 2

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

=item 3

Submit a Parrot Contributor License Agreement; this document signifies that you
have the authority to license your work to Parrot 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.parrot.org/files/parrot_cla.pdf>

=item 4

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

If approved, a metacommitter 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!

=cut