There and Back Again

This is reprint of an email I sent out to pear-dev and the php user groups im active at:

There comes a time in a projects life when even though its been successful and widely used its founders are no longer able to develop it to the extent it needs.
phpDocumentor has reached that point, Greg and I have pushed the project forward for 5 years now, but thats also the problem its just Greg and I.
The bug reports and feature requests keep coming, but the developer time doesn’t.

So this is where you come in, we need some help.

Currently were looking for people to fill in the following roles.
1. People to work on a new Task oriented phpDocumentor guide
2. People to help out with the website, finding articles about phpDocumentor, users of phpDocumentor, and working on the FAQ
3. People to review, triage, write test cases and manage bug reports
4. People to work on new features and refactoring
5. A release manager to handle releases to SourceForge and PEAR, helping with release notes, and tracking down bug fixes

If you’re interested just sign up on the mailing list at: http://lists.bluga.net/mailman/listinfo/phpdocumentor-devel
Send a email introducing yourself and say what you’d like to help with. I’ll currently in London, England so if your in a different time zone
there might be a bit of delay on me replying but if I’m around i’ll attempt to respond as soon as possible.

thanks
-Joshua Eichorn
http://phpdoc.org

Ok I had a bit of a talk with Greg today about phpDocumentor’s future.

I think I convinced him we don’t want to go off into rewrite never-never land for a couple years (read what Joel has to say about rewrites).

So the current plan looks something like this.

1. Merge release_1_2_0 branch back to head (done)
2. Create a quick destination overview (below)
3. Start refactoring

Ok so we want to end up with a model like this:

CommandLineInterface----|
			|------------FlowControl
WebInterface------------|		  |
			|		  |
			|		  |
		ConfigurationStore	  |-------Parser
					  |
					  |-------ClassReflectionTree
					  |
					  |-------DocblockReflectTree
					  |
					  |-------UsesCalculator
					  |
					  |-------DependencyCalculator
					  |
					  |-------TreeWalker
					  |
					  |-------ConvertorCore
							|
				-----------------------------------------
				|					|
			EventImplementation			    Renderer
									|
								     Savant

This means two things, we have a target. Just checkout head to submit patches from.

If you want to help just subscribe to the developer mailing list and introduce yourself.

I just found an article on builder.net about phpDocumentor. Gives a nice overview of what can be done. Our web monkey is also working on updating the phpDocumentor website so soon i’ll have a listing there of all the articles I can find.

If you know of any phpDocumentor articles out there please post them as a trackback or a comment on this article.

phpDocumentor is a big project, and that might make it a little harder for people to get started on it, but just like any project there are a number of easy entries points.

The first is the basic command line and web interfaces. They are made up of only a couple files but that the developers main interaction with the project and also for a number of bugs (#2 and #5 on my last post).

The most important file for both web and cli interfaces is phpDocumentor/Io.inc, the methods in there build and parse options as well as containing some pretty cool methods for matching and ignoring files.

Interface files:

• phpdoc - Shell/Php loader script for cli interface
• phpdoc.bat - Windows equiv to phpdoc
• index.html - Loader file for the web interface
• phpDocumentor.ini - base configuration file
• docbuilder/* - The web interface
• phpDocumentor/phpdoc.inc - Cli bootstrap
• phpDocumentor/common.inc.php - Load ini files setup basic constants
• phpDocumentor/Io.inc - Find files, parse command line parameters

Now I don’t know if basics like this are actually useful, some feedback on what would help a person get started would be great.

I was going to use this as an introduction to my overview post but it seems my lack of shell scripting made things a little harder then I thought.

Anyhow if you don’t count html or compiled templates the 1.2.0 branch of phpDocumentor (these is where 1.3.0x lives), contains 69,847 lines of code. If you add in the documentation that Greg has written were up to 75,257 lines.

Thanks to my co-worker Charles for helping me out.

And the code I ended up using is:
cat `find * | egrep "php$|inc$" | egrep -v "templates_c"` |wc -l

Update:
I ended up including ini files and html files and removing the embedded Smarty and Html Tree menu, for maybe a more accurate count.
Without ini files: 60,322
With ini files: 70,335

Below is a list of bug that I think are easy fixes.

1. 940932 - Manual Version is wrong
2. 951902 - Shell return values for automatic scripting
3. 935785 - the new CSS unviewable with Konqueror
4. 924760 - source rendering in FireFox contains extra newlines
5. 1043330 - Make Command Line Parser support shorter syntax
6. 964248 - Convert invalid characters in package/subpackage names to _

If your interesting on getting started on one of these bugs sign up on the developer list and send an email. I can point you to the classes/files you’ll need to look at to get started hacking.

Since were working on a branch you’ll want to use something like the commands below to checkout code to get started:

cvs -d :pserver:anonymous@phpdoc.org:/opt/cvsroot login
cvs -d :pserver:anonymous@phpdoc.org:/opt/cvsroot co -r release_1_2_0 phpdoc


Another great PhpLondon meeting, made it home by 1am, and didn’t miss any trains.

Spent a lot of time talking about requirments, and saw a demo of an interesting project that implemented dynamic proxying in php (though the code seemed to be a lot more complex then it needed to be).

But i ended the evening on a topic that i’ve been working at for the last 5 years, phpDocumentor.

Now some might saw that phpDocumentor is a successful project, and in some ways it is (all time rank on source forge of 829, 50,000 sf downloads + another 40,000 from pear) but on the number that really drives an open source project were not doing so good.

That important # is active developers, at the moment its really 0. Yep thats right 0, I’m more or less in maintenance mode, put a patch in, respond to bugs queries. And while Greg will be back at some point for now he is working on the PEAR installer. So that leaves no one.

So this is my plan to change things a bit. It means i’ll get a bit more involved for the next few months, and will try to see what it takes to take “I want to help out phpDocumentor” to a new member of the phpDocumentor team.

I will do:

1. Create a list of getting started bugs for new developers to work on
2. Create test cases using simple test for each bug (Marcus promised to help)
3. Create a new mailing list for the project at phpdoc.org (developer-list@phpdoc.org)
4. Commit any back logged patches, and create a short howto how to make a patch
5. Annouce a contest to the PhpLondon and AzPHP users groups where bug fixes will be rewared with prizes (pints of beer unless anyone has a better suggestion)
6. Write up an overview of the phpDocumentor design, and show how to tackle just one part of it, instead of the whole huge code base
7. Blog lots about phpDocumentor and try to get people excited about helping.

What im trying to get out of this is:

1. 2 new developers who fix bugs/commit code on a regular basis
2. Activity outside of some php user groups besides posting on a list or going to a meeting (ie giving back to the php community)
3. A developer to take over the phpDocumentor release process, i’ll still be around but I just don’t have the time and energy to keep pushing in patches, keeping people organized and keeping up a regular release schedule

So if you want to help here’s what you do sign up on the new list (or comment right here). And post on how you think I can help people getted started working on phpDocumentor. If you have time and energy to help that would be even better, sign up and will get the process rolling.

Please remember, I don’t want to spend time setting up source forge and cvs accounts, I don’t need 10 more I want to helps that go no where. So these starter bug fixes will all be patch based, and once you’ve proven your ready to stay with things will set accounts up from there.

There is a PHP user group meeting in London tonight.

Meetings are pretty informal but very informative and a good time. I’ll be there at 7, if your in the London area and haven’t been before tonights the night.