HTTP/1.1 -1 Read error in cache disk data: SuccessContent-Type: text/plain; charset="utf-8" Last-Modified: Sat, 22 Jan 2022 04:27:59 GMT Content-length: 6640 Connection: Close Proxy-Connection: Close X-Cache: HIT from web1.osuosl.org Server: ProxyTrack 0.5 (HTTrack 3.49.2) [[Image(new parrot.png, 96px)]] == Newcomers Welcome! == We're going to do our best to document the experiences of newcomers to Perl, Parrot and Open Source software development. Hopefully this will evolve into a road map for those who wish to contribute but are having trouble getting started. == Before you start == Before you download and compile Parrot, you may want to check you system to make sure you have the following packages installed. * [http://perl.org Perl] (5.8.4 or later is required; run perl --version to find out what you have) * [http://perldoc.perl.org/perldoc.html perldoc] (provided by package {{{perl-doc}}} on Debian/Ubuntu). * [http://git-scm.com/ git] == Getting Parrot == If your going to become part of the development team, you'll need to check out a local copy of the source code. You can visit the [http://www.parrot.org/download download] page on the main Parrot web site for full details. You should take look on the [https://github.com/parrot/parrot/blob/master/README README] file located on Parrot's folder. There you will find tips about installing Git and some more instructions about compiling Parrot. Assuming you've got Perl, perldoc and Git installed you'll be doing something like this. {{{ ~$ git clone git://github.com/parrot/parrot.git ~$ cd parrot ~$ perl Configure.pl ~$ make ~$ make test ~$ make html }}} Running `make install` is not currently recommended. A guide on how to use Git to work on Parrot can be found on [https://github.com/parrot/parrot/blob/master/docs/project/git_workflow.pod docs/git_workflow.pod] == Running Parrot == Make compiled a binary in the parrot build directory. {{{ ~$ ./parrot --version }}} You may want to create a symbolic link to this binary, somewhere in your path, so that you can run parrot from anywhere. {{{ ~$ ln -s ~/parrot/parrot /usr/bin/parrot ~$ parrot --version }}} == Learning Parrot == You've downloaded, configured, compiled, tested and created the html documentation for Parrot. Now it's time to start reading. Parrot's source documentation is stored in [http://en.wikipedia.org/wiki/Plain_Old_Documentation POD] format. If you ran `make html` you can the view the documentation in any HTML browser. The file `docs/html/index.html` is the place to start. An alternative and more flexible method for viewing the documentation is to use [http://search.cpan.org/dist/Pod-Perldoc/lib/perldoc.pod perldoc] to view the actual pod files, formatted as man pages. It cannot be stressed enough how important it is to read the documentation for this project. The bare minimum reading needed to get you off the ground is: * [https://github.com/parrot/parrot/blob/master/docs/intro.pod docs/intro.pod] * [https://github.com/parrot/parrot/blob/master/docs/gettingstarted.pod docs/gettingstarted.pod] The directory `docs/book/` contains a book on Parrot. This book has a finer details of various aspects of Parrot. However be aware that the book in not up to date. After you read those, you'll want to run through all of the tutorials in `examples/tutorial`. Next on your reading list should be the PDDs (Parrot Design Documents) in `docs/ppds`. You will learn much by reading these, so don't skimp. You'll probably need to read some of Parrot's code. [http://coliveira.net/software/tips-to-read-other-peoples-code/ This article] will give you some tips on how to do so effectively. == Contributing == By now you've read the introductory documentation and reviewed the `example/tutorial` files. Now you have to decide what area of the project you'd like to contribute to. === Test Suite === Original Parrot tests were written in Perl. Those Perl tests can be ported to PIR test. This is a good place to earn your feathers and learn more PIR at the same time. [wiki:ConvertTestsToParrot] covers what you'll need to know about the format of a PIR test. If you're not familiar with the test suite functions, you'll want to review `parrot/runtime/library/Test/More.pir`. The functions section gives a description of the different testing functions, mainly: `plan`, `diag`, `ok`, `nok`, `is`, `is_deeply`, `like`, `isa_ok`, `skip`, `isnt` and `todo`. This is a good time to point out that POD can and usually is embedded in PIR files. So if you're in the root build directory, you can run the following to view the module documentation: {{{ ~$ perldoc runtime/parrot/library/Test/More.pir }}} You already know that `make test` runs the test suite, but when working on individual tests you'll want to run only the test you're concerned with. You can do this using Perl's [http://perldoc.perl.org/prove.html prove] for a Perl test, or either `prove` or Parrot itself for PIR tests. {{{ ~$ prove t/oo/names.t t/oo/names....ok All tests successful. Files=1, Tests=2, 0 wallclock secs ( 0.05 cusr + 0.01 csys = 0.06 CPU) or ~$ parrot t/oo/names.t 1..2 ok 1 - HLL obj w/ name different than parrot obj created ok 2 - HLL obj w/ same name as parrot obj not created }}} More information about the subject can be found on our `docs/` folder. More precisely, here: [https://github.com/parrot/parrot/blob/master/docs/tests.pod docs/tests.pod] == Submitting your work == In general you'll need to create a patch and then create a ticket on Parrot's [http://trac.parrot.org/parrot/report/1 ticket tracking system]. Give as much details as you can. A good idea is to provide a list of all files affected with summary of the changes made in each file and the reasons that made you change them. And don't forget to attach your patch directly to the ticket. {{{ ~$ git status ~$ git diff --stat ~$ git diff > names_test_rewrite.patch }}} Once again there is a POD covering this topic. Read [https://github.com/parrot/parrot/blob/master/docs/submissions.pod docs/submissions.pod] for specific details on how to submit your work. == Getting feedback == If the Parrot's ticket tracking system is not enough to discuss about patches you wrote or features that you would like to develop, you can subscribe to the `parrot-dev` mailing list using this [http://lists.parrot.org/mailman/listinfo/parrot-dev subscription form]. There is also an official mailing list called `parrot-users`. The subscription form is available [http://lists.parrot.org/mailman/listinfo/parrot-users here]. For real-time feedback you can go to the `#parrot` channel, available on the `irc.perl.org` network. Parrot developers can be found there in almost any time of the day. cancer problem</strong></a> and odds are it will give you a good chance to sol