Front page | perl.cvs.parrot |
Postings from November 2008
[svn:parrot] r32575 - trunk/docs/book
November 12, 2008 09:53
[svn:parrot] r32575 - trunk/docs/book
Message ID: 20081112175302.3A62FCB9AF@x12.develooper.com
Date: Wed Nov 12 09:53:01 2008
New Revision: 32575
[Book] Fix up the first half of Chapter 2. Fix prose and flow, grammar, and the occasional spelling problem.
--- trunk/docs/book/ch02_getting_started.pod (original)
+++ trunk/docs/book/ch02_getting_started.pod Wed Nov 12 09:53:01 2008
@@ -5,13 +5,13 @@
The Parrot project is specially organized to be light-weight and
-efficient. The project is governed like a meritocracy--people who
+efficient. The project is governed like a meritocracy; people who
make valuable contributions are offered more responsibility. Communication
is relaxed and informal, often intermittent through email and on IRC. As
Dan is so fond of saying, "This is far too important to take seriously."
-The Parrot developers act a bit like a special forces unit--the objective
-is pursued not because of tight control from the top, but because the whole
-team knows the task at hand and does it.
+The Parrot developers act a bit like a special forces unit where the
+objective is pursued because the whole team knows the task at hand, not
+because of any tight control from above.
=head2 Development Cycles
@@ -19,23 +19,29 @@
The Parrot development cycle centers on regular "point releases." A point
-release is a version change, such as 0.4.x to 0.5.x. The architect and
-project manager decide when point releases happen and what features are
-included. Usually one or two solid new features trigger a point release.
+release corresponds to a version change, such as 0.4.x to 0.5.x. These
+releases typically happen monthly, which is good because nobody has
+to guess when the next one will be. The architect and release managers
+decide whether the release is a "major" or minor one, depending on the
+changes that have been made and the features that have been added in the
+previous month. Usually one or two solid new features trigger a major
+point release. The Parrot team has specified a general roadmap of major
+point releases, and the expected features and changes that will trigger
Development proceeds at a steady pace with bugs reported, patches
-submitted, and patches applied. The pace isn't so much a result of
-careful planning as it is the law of averages--on any given day,
-someone, somewhere, is working on Parrot. In periods of high activity
-there are often many more people working on Parrot then just one. A
-release represents a spike in that activity, but since Parrot tends
-to follow the "release early, release often" strategy, these spikes are
-Typically, the release manager for the month declares a feature freeze
-several days before each release. During these freezes all development
-efforts are redirected to testing and bug fixing. This periodic cleanup
-is one of the most valuable aspects of a release.
+submitted, patches applied, and all sorts of other regular development
+tasks performed. The pace isn't so much a result of careful planning as
+it is the law of averages; on any given day someone, somewhere, is
+working on Parrot. In periods of high activity there are often many more
+people working on Parrot N<Or related tools, or high-level language
+compilers, etc.> then just one. Activity tends to spike when a release
+is approaching as last minute bugs, especially bugs in the build system
+or bugs that cause segmentation faults, are found and fixed by the team.
+After the release, there is an influx of new bug reports and other
+feedback as the casual users and testers get their hands on the newest
+version. These regular swells of activity are one of the major reasons
+why Parrot has monthly releases.
=head2 Getting Involved
@@ -53,10 +59,10 @@
for other communications media, such as IRC.
The Parrot developers, along with other volunteers and well-wishers
-tend to congregate on IRC as well. They maintain a chatroom C<#parrot>
-on the U<irc://irc.perl.org> server. To get real-time answers to
-questions, or just to see how things are progressing, the chatroom
+tend to congregate on IRC to have more in-depth discussions. They
+maintain a chatroom C<#parrot> on the U<irc://irc.perl.org> server.
+To get real-time answers to questions, or just to see how things are
+progressing, the chatroom is the place to be.
=head3 Use the source
@@ -65,9 +71,11 @@
The second step to participating in Parrot development is to get a
copy of the source code. If you just want to try it out--experiment
-with a few features and see how it feels--you're probably best off
-downloading a tarball. For the most stable copy, grab the latest point
-release from CPAN. The sure way to get the most recent release is at
+with a few features and see how it feels--the best options is to
+download the most recent point release for your system. Point releases
+are usually packaged up for easy download and install for various
+platforms, including Windows, Debian, and Redhat. Point releases are
+also available from CPAN. The sure way to get the most recent release is at
U<http://search.cpan.org/dist/parrot/> (or search for "parrot" in
"Distributions"). If you want something a little more cutting edge than
the packaged release, a new snapshot of the subversion repository is
@@ -75,40 +83,62 @@
If you plan to get involved in development, you'll want to check out
-the source from the subversion repository. Anyone can get anonymous
-access, committers use their U<http://auth.perl.org> username.
+the source from the subversion repository directly. Anyone can get
+anonymous access to read the files and download a working copy to
+explore and test. For commit access, volunteers need a
+U<http://auth.perl.org> username, and need to be approved by a
+Metacommiter. To download the most recent version from SVN, type this
+command into your terminal N<This is for Linux users, on Mac or
+Windows systems, follow the instructions from your SVN client>:
svn co https://svn.perl.org/parrot/trunk parrot
There's also a web interface for viewing files in the repository at
-Now that you've got the source, take a moment to look around. The code
-changes constantly, so a detailed description of every file is
-impossible. But a few road signs are helpful starting out.
+The repository is large and complex, so it's worth taking a little bit
+of time to explore. The code changes constantly, but most files and
+functions have informative descriptions to help keep track of things.
The most important top-level directory is F<docs/>. The content isn't
always up to date, but it is a good place to start. F<parrot.pod>
provides a quick overview of what's in each documentation file. If you're
-a capable writer and know a thing or two about how Parrot works,
-the documentation is a great place to start contributing.
+a capable writer and know a thing or two about how Parrot works, the
+documentation is a great place to start contributing. This book that
+you're reading right now was created in F<docs/book/> by ordinary
+contributors. Most other documentation files found here are parsed and
+converted to HTML for display at U<http://www.parrot.org>.
The F<languages/> directory contains the code that implements various
-language compilers: Perl 6, Python ("Pynie"), Ruby ("Cardinal"), PHP
-("Pipp"), Lisp, Lua, Tcl ("partcl"), WMLScript, Forth, Scheme,
-Befunge, BASIC, and many others. These language compilers are in
-various stages of partial completion. The file F<LANGUAGES.STATUS>
-provides meta information on the included languages and on the many
-language projects that are being developed and maintained outside the
-Parrot repository. If you have a language you're particularly
-interested to see implemented on Parrot, you can see how far along the
-effort is, or you can start the work to implement it yourself.
+language compilers N<This isn't entirely true. As of the 1.0 release
+of Parrot, all HLLs are supposed to reside elsewhere, not in the
+Parrot repository. If the languages disappear from there, we'll
+probably be nice enough to leave a note telling you where it went>:
+Perl 6, Python ("Pynie"), Ruby ("Cardinal"), PHP ("Pipp"), Lisp, Lua,
+Tcl ("partcl"), WMLScript, Forth, Scheme, Befunge, BASIC, and many
+others. These language compilers are in various stages of partial
+completion. The file F<LANGUAGES.STATUS> provides meta information on
+the included languages and on the many language projects that are
+being developed and maintained outside the Parrot repository. If you
+have a language you're particularly interested to see implemented on
+Parrot, you can see how far along the effort is, or you can start the
+work to implement it yourself. We'll talk more about creating new
+compilers in Chapter 10: High-Level Languages, if you're interested.
The F<lib/> directory contains Perl 5 classes currently used in
-developing Parrot. The F<src/pmc/> directory contains the C source
-code for Parrot classes (PMCs, which you'll read more about in
-A<CHP-9>Chapter 9). The F<examples/> directory contains some example
-Parrot assembler code, as well as benchmarks.
+developing, building, and testing Parrot. The F<src/pmc/> directory
+contains the C source code for Parrot classes (PMCs, which you'll read
+more about in A<CHP-11>Chapter 11).
+Most Parrot development happens in F<src/> for the C source code, and
+F<include/parrot/> for the C development header files.
+Libraries for use by programs running on Parrot are found in F<runtime/>.
+The F<examples/> directory contains some example Parrot PIR and Assembly
+code, as well as benchmarks. More discussions about these topics will be
+found in A<CHP-3> Chapter 3, A<CHP-5> Chapter 5, and A<CHP-7> Chapter 7
=head1 Building Parrot
[svn:parrot] r32575 - trunk/docs/book