Soylent POE is made of People. Lots of people. People just like you.

Most people contribute small changes to POE: Patches, bug reports, and motivation. We love these people. If you're one of them, thank you!

A very few go well beyond the casual patch. They tackle major bugs, submit regular changes, and eventually enter the ranks of POE committers. We love them, too. Heck, we are them!

There's nothing stopping you, gentle reader, from joining us, except your trepidation. This is a natural fear of the unknown. Of failure. Don't worry. We don't really care. We've been there, and we understand.

This document is designed to help you get over the fear of developing for POE. I hope you find it useful.

POE developers need to do a few things:

Let's talk about these in more detail.

Stay in contact.

POE development isn't done in a vacuum. Developers are expected to discuss their plans in public and consider any feedback they get. The official design process applies to everyone, even (some would say especially) POE's creator.

Generally speaking, silence is consent. If an idea survives a week or more in public without an objection, it's probably ok.

POE's discussion list is an ideal place to ask for guidance and to help guide others. It's where new ideas are discussed before they become tasks in POE's request tracker.

POE's commit messages are blogged at [POE's tracker at CIA]. Committers should subscribe to it so they don't duplicate effort.

POE's developers hang out on IRC a lot. You can usually find them at irc.perl.org, channel #poe. Some of them lurk on #perl (and #poe) on several networks. IRC is great for kicking around preliminary ideas and getting immediate feedback (timezones and schedules permitting). They're not a substitude for the mailing list, however.

Acquire POE's source.

It pays to keep up to date. The last thing you want to hear after spending an hour on a patch is "that's already been done" or "your patch doesn't apply cleanly, could you redo it with the latest code?"

You'll need CVS. Yes, we know that several other revision control systems work better, but POE is hosted at SourceForge. SourceForge only supports CVS as of this time. You'll need to deal with it for the time being.

Acquiring a CVS client is outside the scope of this document. Sorry about that. Check to see if your operating system comes with it, or if it's one of the packages or ports available to you. In the worst case, the web probably knows. Try searching for 

  cvs your_OS

and good luck.

Once you have CVS, you'll need a place where all the files go. I use ~/projects/poe. You'll probably use something different. It doesn't matter as long as you're in that directory when you make your initial checkout.

So how do you get a current copy of POE's repository? If you're using a command line version of CVS, it's pretty easy. The first step is to log in. 

  cd ~/projects/poe    # for example
  cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/poe login

You'll be prompted for a password, but you don't need one. Just hit enter.

Next you'll need to check out a copy of the repository. This grabs the latest versions of all the files, including a bunch of side projects you may find interesting. 

  cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/poe co poe

POE's repository includes extras and side projects, like POE's wiki source, a documentation project, and some other things. If you want to poke around in the back alleys of POE development, replace "co poe" with "co .". Most people don't need these things, but they may be interesting.

Still with us? Congratulations, you're the proud owner of the latest and greatest POE code in development. If you ever need to update your source files, simply 

  cvs update -dP .

from ~/projects/poe (for example), and your copy will be synchronized with changes from other developers.

Download other necessary modules.

POE can use a lot more modules than come with Perl by default. The more of them you have, the more thoroughly you can test your changes.

The easiest way to install them is to let Makefile.PL do it for you. 

  perl Makefile.PL

The program will ask you if you'd like to install any modules that are missing. You must answer yes to the required modules, but you're welcome to skip the optional ones. The resulting Makefile will automatically attempt to download any approved modules and their dependencies when you run 

  make

The graphical toolkits take a long time. You may want to skip them on slow machines or if you're in a hurry.

Get familiar with POE's code.

POE is a big project. It is comprised of many modules, all working in concert to give you the best event driven experience Perl has to offer. Most new developers will look at this and become instantly lost when trying to figure out what's going on.

We recommend starting with the public interfaces and working towards the lower level things. Most of POE's public interfaces are in POE::Kernel, so you might start there. For the moment, trust the names of the lower-level methods being called. When you understand what's going on at that level, it's time to drill down into the lower ones.

Don't hesitate to ask the mailing list or a developer what something means.

ToDo: Explain naming conventions so that methods can be mapped to module names for easy location. This will probably be deferred until spare time arises, or someone actually asks.

Most modules aren't documented as well as they should be. Some (usually the internal ones) are barely documented at all. Extending and correcting the documentation is a good introductory task for someone trying to get up to speed with POE's source code.

Browse POE's open tasks.

POE's pretty cool, but there's still a lot of work to be done. Where you start, and what you work on is up to you, but we'll be happy to make suggestions.

POE's to-do lists are strewn about in several places. We have plans to consolidate them, but not enough time to do it. This might be a good starter task if you like to organize things. Otherwise, you might want to look in these places:

Here are some places to look for tasks:

[POE's bug tracker] is open for anyone to browse. You can add your own tasks by sending e-mail to [1]. Claiming and resolving tasks is done through the web interface, but you'll need a CPAN ID for that. We can help you acquire a CPAN ID, if you'd like one.

[POE's live notes] are a bunch of half-baked ideas in search of more conceptual development. This is the ideal place to work if you're an "idea person".

The "Stuff In Progress" section lists tasks currently being worked on. Not all of them are current, and many of them are stalled for one reason or another. Some of them are mirrored in POE's RT queue, and the others need to be. You're welcome to pick one up and go.

The "Stuff Under Consideration" are ideas in search of brains to develop them. We're looking for general input on POE's future. You're welcome to sign up to the wiki and add your own comments, or even adopt an RFC outright.

ToDo: Document the procedure for turning an RFC into an RT ticket, including passing the mostly completed idea through the mailing list.

POE's documentation needs help badly. This can be as casual as tidying up part of the web site or as involved as writing new documentation. We recommend starting small. Big tasks like "rewrite the documentation" are daunting and have discouraged several volunteers before you.

If you're a testing guru, POE needs better test coverage. We've just committed a new testing framework, and it's just begging for more tests.

ToDo: Document the testing tools and procedures.

And more stuff than we can list here. In fact, you can probably think of two or three things POE needs that haven't been mentioned here. You're welcome to propose new tasks on the mailing list. If the collective wisdom of POE's community deems them worthy, they'll become full-fledged RT tickets.

Consider new features before proposing them.

New features for POE's core distribution (POE-version.tar.gz) are usually rejected. This is not a personal issue. It's to stop POE's "core" from growing unnecessarily.

The feature must be impossible to implement outside POE's core distribution. If your proposed feature can be released as a POE::Component, then we will insist that it be done.

Changes should not break backward compatibility. If they do, there must be a good reason for it. We may insist that your changes be phased in over the course of three or more CPAN releases, to give developers a chance to adapt to the change in their deployed systems.

Changes to public interfaces should include documentation patches.

We don't currently insist that tests be submitted with changes, but we may in the future. You still get big bonus points for sending in tests with your patches.

ToDo: There are other criteria that must be documented here.

Claim a task, and set reasonable goals.

If you don't have RT access (and you won't to begin with), then announce your intentions to do something on POE's mailing list. This will prevent others from duplicating your work (or you from duplicating someone else's), and it has the potential to gather interest from people who may be able to help you out.

It's vital to set reasonable goals, especially if you've taken on a large task. If you get part of the way into a task, and it suddenly looks like more than you can handle, just say so. People on the mailing list can help break it down into manageable bites.

Once you've claimed a task, keep us up to date on it. Let us know what milestones you've reached, how we can help, and even whether it's stalled. You lose no honor in voluntarily giving up on a project you can't finish. In fact, we'll appreciate your honesty. It also gives others an opportunity to build upon your work, rather than have your efforts go to waste.

Submit changes.

Submit patches regularly. In the grand scheme of things, your work doesn't count if it isn't shared.

We can apply your changes so other development doesn't conflict with them. You can synchronize your source files with other developers' changes. Everybody wins!

We'll also review and give feedback on your changes, if you want. And if your patches are consistently good, we'll probably offer you direct commit access. That saves us all time and effort.

We have one major requirement for submissions or commits. Your changes pass "make test" before you submit or commit them. Otherwise we're flexible.

What did we miss?

Ask the mailing list if you have any other questions. Someone will work the answers into the next revision of this document.