/ 
parrot-0.1.1
/ docs/submissions.pod

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, then submit 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.

However, if you do know how to fix the problem you encountered, then think about submitting a patch.

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.

  1. Create the patch.

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

    Single diff

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

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

    Win32 users will probably need -ub.

    Recursive diff

    If the change is more wide-ranging, then create an identical copy of parrot in parrotdev 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 parrotdev.

    cd parrotdev
diff -ur --exclude=CVS parrot parrot.new > docs.patch

    OS X users should also include --exclude=.DS_Store.

  2. Create a plain text email.

  3. Set the recipient to bugs-parrot at bugs6 dot perl dot org.

  4. Give the message a clear and concise subject.

    Prefix it with a [PATCH] identifier.

  5. The message body should contain an explaination of the purpose of the patch, and a list of all files affected with summary of the changes made in each file.

  6. Attach the patch file(s).

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

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

  7. Send the mail.

Applying Patches

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

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

cd parrot
patch -p0 < single.patch

For recursive diff patches, copy the patch file to parrotdev, and run:

cd parrotdev
patch -p0 < recursive.patch

How To Submit Something New

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

  1. Create a plain text email.

  2. Set the recipient to bugs-parrot at bugs6 dot perl dot org.

  3. Give the message a clear and concise subject.

    Prefix it with a [NEW] identifier.

  4. The message body should contain an explaination of the purpose of the feature you are adding.

  5. Attach the file(s).

    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.

  6. Send the mail.

What Happens Next?

RT creates a ticket for the submission, and you will receive an auto 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 CVS commit authority will commit it to CVS once it is clear that it is the right thing to do.

Even those developers with CVS 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 http://bugs6.perl.org/. If you have trouble logging in try username guest with password guest.

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

HISTORY

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