NAME

docs/submissions.pod - Parrot Submission Instructions

ABSTRACT

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

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 parrotbug utility. The simplest way to use it is to run

    % ./parrotbug

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

If you just want to use email to create the bug report, send an email to tickets@parrot.org.

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

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.

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.
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.
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 parrot's --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.

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 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
                |
                +--> ...
git
If you are working with a git repository of parrot then please generate your patch with git diff. 
    cd parrot
    git diff > my_contribution.patch
Single 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 diff for each file. The diff should be created in parrot. Please be sure to create a unified diff, with diff -u. 
    cd parrot
    diff -u docs/submissions.pod docs/submissions.new > submissions.patch
Win32 users will probably need to specify -ub.
Recursive diff
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 --exclude=.DS_Store.
CREDITS
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.

How To Submit A Patch

  1. Go to Parrot's ticket tracking system at https://trac.parrot.org/parrot/. Log in, or create an account if you don't have one yet.
  2. If there is already a ticket for the bug or feature that your patch relates to, just attach the patch directly to the ticket.
  3. Otherwise select "New Ticket" at the top of the site. https://trac.parrot.org/parrot/newticket
  4. Give a clear and concise Summary. You do NOT need to prefix the Summary with a [PATCH] identifier. Instead, in the lower-right corner of the newticket page, select status new in the Patch status drop-down box.
  5. The Description 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 diffstat(1) utility when run on your patch(s) may be included at the bottom of the message body.
  6. Set the Type of the ticket to "patch". Set other relevant drop-down menus, such as Version (the version of Parrot where you encountered the problem), Platform, or Severity. As mentioned above, select status new in the Patch status drop-down box.
  7. Check the box for "I have files to attach to this ticket". Double-check that you've actually done this, because it's easy to forget.

    8. DO NOT paste the patch file content into the Description.

  8. Click the "Create ticket" button. On the next page attach your patch file(s).

Applying Patches

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

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

    cd parrot
    git apply some.patch

For recursive 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.

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

How To Submit Something New

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

  1. Add your new file path(s), relative to parrot, to the file MANIFEST. Create a patch for the MANIFEST file according to the instructions in How To Submit A Patch.
  2. If you have a new test script ending in .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:
    3.     cd parrot
    diff -u /dev/null newfile.t > newfile.patch
  3. Go to Parrot's ticket tracking system at https://trac.parrot.org/parrot/. Log in, or create an account if you don't have one yet.
  4. Select "New Ticket" https://trac.parrot.org/parrot/newticket.
  5. Give a clear and concise Summary.

    6. Prefix it with a [NEW] identifier.

  6. The Description should contain an explanation of the purpose of the feature you are adding. Optionally, include the output of the diffstat(1) utility when run on your patch(es).
  7. Set the Type of the ticket to "patch". Set other relevant drop-down menus, such as Version, Platform, or Severity.
  8. Check the box for "I have files to attach to this ticket"

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

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

  9. Click the "Create ticket" button. On the next page attach the patch for MANIFEST and your new file(s).

What Happens Next?

If you created a new ticket for the submission, you will be taken to the page for the new ticket and can check on the progress of your submission there. This identifier should be used in all correspondence concerning the submission.

Everyone on Trac sees the submission and can comment on it. A developer with git commit privileges can commit it to git once it is clear that it is the right thing to do.

However developers with commit privileges may not commit your changes immediately if they are large or complex, as we need time for peer review.

A list of active tickets can be found here: http://trac.parrot.org/parrot/report/1

A list of all the unresolved patches is at: http://trac.parrot.org/parrot/report/15

Patches for the Parrot website

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

Getting Commit Privileges

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

  1. Submit several high quality patches (and have them committed) via the process described in this document. This process may take weeks or months.
  2. Obtain a Trac account at https://trac.parrot.org/parrot
  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.

    4. http://www.parrot.org/files/parrot_cla.pdf

  4. Request commit access via the 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.

    5. 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!