/ 
parrot-0.5.3
/ 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, or (see below) getting commit privileges.

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.

  1. Create the patch.

    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
            |
            +--> ...
    svn

    If you are working with a checked out copy of parrot then please generate your patch with svn diff.

    cd parrot
svn status
svn 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.

    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='.svn' parrot parrot.new > docs.patch

    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.

  2. Create a plain text email.

  3. Set the recipient to parrotbug at parrotcode dot org.

  4. Give the message a clear and concise subject.

    Prefix it with a [PATCH] identifier.

  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 diffstat(1) utility when run on your patch(s) may be included at the bottom of the message body.

  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 SVN.

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

cd parrot
patch -p0 < some.patch

For recursive diff patches, copy the patch file to 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.

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

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 above 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:

    cd parrot
diff -u /dev/null newfile.t > newfile.patch

  3. Create a plain text email.

  4. Set the recipient to parrotbug at parrotcode dot org.

  5. Give the message a clear and concise subject.

    Prefix it with a [NEW] identifier.

  6. The message body should contain an explanation of the purpose of the feature you are adding. Optionally, the output of the diffstat(1) utility when run on your patch(s) may be included at the bottom of the message body.

  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.

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

  8. Send the mail.

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

A Parrot Bug Summary page is also generated and can be viewed here https://rt.perl.org/rt3/NoAuth/parrot/Overview.html

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

Patches for the Parrot website

The sources for 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 webmaster at perl dot org, and cc parrot-porters at perl dot org.

Getting Commit Privileges

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

  1. Submit one or more patches via the process described in this document that are accepted.

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

  3. Request commit access via the parrot-porters mailing list, or via IRC (#parrot on irc.perl.org). The people who can do this are called "metacommitters"; see RESPONSIBLE_PARTIES for the current list.

Thanks for your help!

HISTORY

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