docs/submissions.pod - Parrot Submission Instructions
How to submit bug reports, patches and new files to Parrot.
If you encounter an error while working with Parrot and don't understand what is causing it, create a bug report using the parrotbug utility. The simplest way to use it is to run
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.
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.
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.
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.
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
--hash-seed parameter. To determine what seeds are causing the error, Parrot can be rebuilt with
DEBUG_HASH_SEED set to
1, which will cause
parrot to output the hash seed being used on every invocation.
Try to keep your patches specific to a single change, and ensure that your change does not break any tests. Do this by running
make test. If there is no test for the fixed bug, please provide one.
In the following examples, parrot contains the Parrot distribution, and workingdir contains parrot. The name workingdir is just a placeholder for whatever the distribution's parent directory is called on your machine.
workingdir | +--> parrot | +--> LICENSE | +--> src | +--> tools | +--> ...
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 http://help.github.com/send-pull-requests/
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
diff for each file. The
diff should be created in parrot. Please be sure to create a unified diff, with
cd parrot diff -u docs/submissions.pod docs/submissions.new > submissions.patch
Win32 users will probably need to specify
If the change is more wide-ranging, then create an identical copy of parrot in workingdir and rename it parrot.new. Modify parrot.new and run a recursive
diff on the two directories to create your patch. The
diff should be created in workingdir.
cd workingdir diff -ur --exclude='.git' parrot parrot.new > docs.patch
Mac OS X users should also specify
Each and every patch is an important contribution to Parrot and it's important that these efforts are recognized. To that end, the 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 CREDITS as part of their patch.
The format for entries in CREDITS is defined at the top of the file.
The preferrred method to submit matches to Parrot is as pull requests via github. Please follow the instructions at http://help.github.com/send-pull-requests/.
You may wish to apply a patch submitted by someone else before the patch is incorporated into git
diff patches or
git patches, copy the patch file to parrot, and run:
cd parrot git apply some.patch
diff patches, copy the patch file to 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.
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
In order to keep the two different checks synchronized, the MANIFEST and MANIFEST.SKIP file should be regenerated with:
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
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: https://github.com/parrot/parrot/issues?state=open
The http://www.parrot.org website is hosted in a Drupal CMS. Submit changes through the usual ticket interface in Trac.
If you are interested in getting commit privileges to Parrot, here is the procedure:
parrot-devmailing 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
RESPONSIBLE_PARTIES for the current list. Welcome aboard!
Thanks for your help!