<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Parrot - Parrot Submission Instructions</title>
<link rel="stylesheet" type="text/css"
href="../../resources/parrot.css"
media="all">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<div id="wrapper">
<div id="header">
<a href="http://www.parrot.org">
<img border=0 src="../../resources/parrot_logo.png" id="logo" alt="parrot">
</a>
</div> <!-- "header" -->
<div id="divider"></div>
<div id="mainbody">
<div id="breadcrumb">
<a href="../../html/index.html">Home</a> » Parrot Submission Instructions
</div>
<h1><a name="NAME"
>NAME</a></h1>
<p>docs/submissions.pod - Parrot Submission Instructions</p>
<h1><a name="ABSTRACT"
>ABSTRACT</a></h1>
<p>How to submit bug reports,
patches and new files to Parrot.</p>
<h1><a name="How_To_Submit_A_Bug_Report"
>How To Submit A Bug Report</a></h1>
<p>If you encounter an error while working with Parrot,
and don't understand what is causing it,
then create a bug report using the <em><a href="../parrotbug.html">parrotbug</a></em> utility.
The simplest way to use it is to run</p>
<pre> % ./parrotbug</pre>
<p>in the distribution's root directory, and follow the prompts.</p>
<p>However, if you do know how to fix the problem you encountered, then think about submitting a patch, or (see below) getting commit privileges.</p>
<h1><a name="How_To_Submit_A_Patch"
>How To Submit A Patch</a></h1>
<p>Try to keep your patches specific to a single change, and ensure that your change does not break any tests. Do this by running <code>make test</code>. If there is no test for the fixed bug, please provide one.</p>
<ol>
<li>Create the patch.</li>
<p>In the following examples, <em>parrot</em> contains the Parrot distribution, and <em>workingdir</em> contains <em>parrot</em>. The name <em>workingdir</em> is just a placeholder for whatever the distribution's parent directory is called on your machine.</p>
<pre> workingdir
|
+--> parrot
|
+--> LICENSE
|
+--> src
|
+--> tools
|
+--> ...</pre>
<dl>
<dt><a name="svn"
><b><code>svn</b></code></a></dt>
If you are working with a checked out copy of parrot then please generate your patch with <code>svn diff</code>.
<pre> cd parrot
svn status
svn diff > my_contribution.patch</pre>
<dt><a name="Single_diff"
>Single <b><code>diff</b></code></a></dt>
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 <code>diff</code> for each file. The <code>diff</code> should be created in <em>parrot</em>. Please be sure to create a unified diff, with <code>diff -u</code>.
<pre> cd parrot
diff -u docs/submissions.pod docs/submissions.new > submissions.patch</pre>
Win32 users will probably need to specify <code>-ub</code>.
<dt><a name="Recursive_diff"
>Recursive <b><code>diff</b></code></a></dt>
If the change is more wide-ranging, then create an identical copy of <em>parrot</em> in <em>workingdir</em> and rename it <em>parrot.new</em>. Modify <em>parrot.new</em> and run a recursive <code>diff</code> on the two directories to create your patch. The <code>diff</code> should be created in <em>workingdir</em>.
<pre> cd workingdir
diff -ur --exclude='.svn' parrot parrot.new > docs.patch</pre>
Mac OS X users should also specify <code>--exclude=.DS_Store</code>.
<dt><a name="CREDITS"
><b><code>CREDITS</b></code></a></dt>
Each and every patch is an important contribution to Parrot and it's important that these efforts are recognized. To that end, the <em><a href="../CREDITS.html">CREDITS</a></em> 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 <em><a href="../CREDITS.html">CREDITS</a></em> as part of their patch.The format for entries in <em><a href="../CREDITS.html">CREDITS</a></em> is defined at the top of the file.</dl>
<li>Go to Parrot's ticket tracking system at <a href='https://trac.parrot.org/parrot/'>https://trac.parrot.org/parrot/</a>. Log in, or create an account if you don't have one yet.</li>
<li>Select "New Ticket" <a href='https://trac.parrot.org/parrot/newticket'>https://trac.parrot.org/parrot/newticket</a>.</li>
<li>Give a clear and concise Summary.</li>
<p>Prefix it with a <code>[PATCH]</code> identifier.</p>
<li>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 <code>diffstat(1)</code> utility when run on your patch(s) may be included at the bottom of the message body.</li>
<li>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.</li>
<li>Check the box for "I have files to attach to this ticket"</li>
<p>Double-check that you've actually done this, because it's easy to forget.</p>
<p><b>DO NOT</b> paste the patch file content into the Description.</p>
<li>Click the "Create ticket" button. On the next page attach your patch file(s).</li>
</ol>
<h1><a name="Applying_Patches"
>Applying Patches</a></h1>
<p>You may wish to apply a patch submitted by someone else before the patch is incorporated into SVN.</p>
<p>For single <code>diff</code> patches or <code>svn</code> patches, copy the patch file to <em>parrot</em>, and run:</p>
<pre> cd parrot
patch -p0 < some.patch</pre>
<p>For recursive <code>diff</code> patches, copy the patch file to <em>workingdir</em>, and run:</p>
<pre> cd workingdir
patch -p0 < some.patch</pre>
<p>In order to be on the safe side run 'make test' before actually committing the changes.</p>
<h2><a name="Configuration_of_files_to_ignore"
>Configuration of files to ignore</a></h2>
<p>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</p>
<pre> svn status</pre>
<p>or</p>
<pre> perl tools/dev/manicheck.pl</pre>
<p>The list of these ignore files can be set up with:</p>
<pre> svn propedit svn:ignore <PATH></pre>
<p>In order to keep the two different checks synchronized, the MANIFEST and MANIFEST.SKIP file should be regenerated with:</p>
<pre> perl tools/dev/mk_manifest_and_skip.pl</pre>
<h1><a name="How_To_Submit_Something_New"
>How To Submit Something New</a></h1>
<p>If you have a new feature to add to Parrot, such as a new test.</p>
<ol>
<li>Add your new file path(s), relative to <em>parrot</em>, to the file MANIFEST. Create a patch for the MANIFEST file according to the instructions in <b>How To Submit A Patch</b>.</li>
<li>If you have a new test script ending in <code>.t</code>, 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:</li>
<pre> cd parrot
diff -u /dev/null newfile.t > newfile.patch</pre>
<li>Go to Parrot's ticket tracking system at <a href='https://trac.parrot.org/parrot/'>https://trac.parrot.org/parrot/</a>. Log in, or create an account if you don't have one yet.</li>
<li>Select "New Ticket" <a href='https://trac.parrot.org/parrot/newticket'>https://trac.parrot.org/parrot/newticket</a>.</li>
<li>Give a clear and concise Summary.</li>
<p>Prefix it with a <code>[NEW]</code> identifier.</p>
<li>The Description should contain an explanation of the purpose of the feature you are adding. Optionally, include the output of the <code>diffstat(1)</code> utility when run on your patch(es).</li>
<li>Set the Type of the ticket to "patch". Set other relevant drop-down menus, such as Version, Platform, or Severity.</li>
<li>Check the box for "I have files to attach to this ticket"</li>
<p>Double-check that you've actually done this, because it's easy to forget.</p>
<p><b>DO NOT</b> paste the content of the new file or files into the body of the message.</p>
<li>Click the "Create ticket" button. On the next page attach the patch for MANIFEST and your new file(s).</li>
</ol>
<h1><a name="What_Happens_Next?"
>What Happens Next?</a></h1>
<p>Trac 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.</p>
<p>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.</p>
<p>Even developers with SVN commit authority stick to this scheme for larger or more complex changes, to allow time for peer review.</p>
<p>You can check the progress of your submission at the Parrot bugs page <a href='http://bugs6.perl.org/'><a href="http://bugs6.perl.org/">http://bugs6.perl.org/</a></a>. If you have trouble logging in try username <code>guest</code> with password <code>guest</code>.</p>
<p>A Parrot Bug Summary page is also available from <a href='https://rt.perl.org/rt3/NoAuth/parrot/Overview.html'>https://rt.perl.org/rt3/NoAuth/parrot/Overview.html</a></p>
<p>A list of all the unresolved patches is at <a href='http://www.parrotcode.org/openpatches.html'><a href="http://www.parrotcode.org/openpatches.html">http://www.parrotcode.org/openpatches.html</a></a></p>
<h1><a name="Patches_for_the_Parrot_website"
>Patches for the Parrot website</a></h1>
<p>The <a href='http://www.parrot.org'><a href="http://www.parrot.org">http://www.parrot.org</a></a> website is hosted in a Drupal CMS. Submit changes through the usual ticket interface in Trac.</p>
<h1><a name="Getting_Commit_Privileges"
>Getting Commit Privileges</a></h1>
<p>If you are interested in getting commit privileges to Parrot, here is the procedure:</p>
<ol>
<li>Submit several high quality patches (and have them committed) via the process described in this document. This process may take weeks or months.</li>
<li>Obtain a Trac account at <a href='https://trac.parrot.org/parrot'>https://trac.parrot.org/parrot</a></li>
<li>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.</li>
<p><a href='http://www.parrot.org/files/parrot_cla.pdf'><a href="http://www.parrot.org/files/parrot_cla.pdf">http://www.parrot.org/files/parrot_cla.pdf</a></a></p>
<li>Request commit access via the <code>parrot-dev</code> mailing list, or via IRC (#parrot on irc.parrot.org). The existing committers will discuss your request in the next couple of weeks.</li>
<p>If approved, a metacommitter will update the permissions to allow you to commit to Parrot; see <code>RESPONSIBLE_PARTIES</code> for the current list. Welcome aboard!</p>
</ol>
<p>Thanks for your help!</p>
</div> <!-- "mainbody" -->
<div id="divider"></div>
<div id="footer">
Copyright © 2002-2009, Parrot Foundation.
</div>
</div> <!-- "wrapper" -->
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
cd14cddf3b3ceaf1193157472227757a
>
files
>
176
