my gsoc proposal submitted to php.net

Proposal: Online editor for the PHP Manual ... http://wiki.php.net/gsoc/2009#online_editor_for_the_php_manual

Currently, the documentation work is synchronized by cvs. But still, there are potential conflicts due to redundant work. Besides, it's not that easy to share the works or even pipelining the works in a distributed environment. Therefore, a centralized environment is introduced. 

The editor is still under development and the source can be found by http://cvs.php.net/viewvc.cgi/doc-editor/ 

Short Description: In order to ease the work of PHP Documentation Group, work on Online Editor for PHP Manual has already started by Yannick... The Online Editor mimicks an offline PHP documentation environment by using ExtJS as ide alike ui and providing xml-editor with CodeMirror syntax highlighting. The documentation group can make changes online, DocBook syntax check, CVS Log/Diff/Commit, patch review list, etc.

Full Description:

PhD OE allows PHP Documentation Group to carry documentation right ahead through the browser instead of using cvs to synchronize their local copy. There is ide alike ui on PhD OE so that the doc-group can directly edit the PHP DocBook xml online. Despite, PhD OE also eases the collaboration in an open documentation environment. Doc-group can share the workloads easily since they no longer need to pass the local modified copies around but on PhD OE. In addition to this, PhD OE does allow community contributor to submit patch so that the doc-group can review the patch in a centralized location like an issue list.

To find out the implemented features of PhD OE, visit following posts on mailing list:

• http://marc.info/?l=phpdoc&m=123394012724778&w=4
• http://marc.info/?l=phpdoc&m=123543064407717&w=4

Currently, there are some opening issues on the TODO list (found by - http://cvs.php.net/viewvc.cgi/doc-editor/TODO?revision=1.5&view=markup). One of the major task is to "Split main.js into several objects & files" because of the coding readability, continunity, and scaliability. main.js contains ui of PhD OE. There are 6922 lines of code in revision 1.21. It is obvious that maintaining such a large piece of codes is tidous and not that good. Thus, this proposal describe how to split the main.js and merge the js for deployment.

Right before talking about the split, let's see how to merge. ExtJS ant script make use of YUI compressor. So, there's no doublt that YUI compressor is a good choice to merge js in this project as the ui depends on ExtJS. Anyway, moving back to the split, main.js can be split based on module. I suggest Java alike model using 1 module 1 class 1 js. This is the practice I used in my own ExtJS project. Nevertheless the split is time consuming, the effort spent on this kind of refactoring allows me to better understand how the ui works and improve the structure. The proposed approach follows.

1. Fork a branch to work on refactoring. The trunk keeps on development
2. Refactor and Test the branch... Testing is important here! No failure should be induced by refactoring.
3. Merge the modified trunk to the refactored branch.
4. Freeze trunk, test the merge.
5. Done.

Another task is to "Clean up class.php". Again, a refactoring task. class.php is the "bootstrap" residing on the apache server ... with 4075 lines of code in revision 1.21. As written in the TODO list, initial ideas for refactoring already exist.  It would be splited into several smaller classes that are quite relatively independent to each other. The proposed appraoch would be somehow the same as refactoring main.js. Fork, Refactor & Test, Merge, Freeze & Test, complete!

Thirdly, according to the TODO list again... the mod_rewrite task is another "better to have first". It makes the codes look much better to understand. This task is pretty strict forward. Design the pattern, write the regular expression on apache conf (.htaccess could be the choice). And then, reflects the changes in both php and js. It's totally different from refactoring, no forking and no code freezing.

Finally, if there's still plenty of time, I would like to propose that the modified but not-yet-saved file should have a lock or google-doc alike collaborative editing. When someone is editing a file with file-based locking, others cannot edit it at the same time before the file is commited (lock released). This reduce the chance of having conflict in modification. If collaborative editing is considered, high level DocBook xml-tag locking can be considered. This means ... partly locking the file so that anyone can edit different parts of the same file. When conflict occur, notify the editors. This would be another busy task.

Timeline:

Community Bonding Period - Study current PhD OE architecture. Confirm refactoring procedures and exact deliverables with mentor.

May 23 ~ June 20 [around 4 man week] - Refactor & Test main.js

June 20 ~ June 27 [around 1 man week] - Merge Refactored code with trunk + Testing + Documentation

June 27 ~ July 4 - [around 1 man week] - Compile interim report

July 4 ~ July 18 [around to 3 man week] - Refactor & Test class.php

July 18 ~ July 25 [around 1 man week] - Merge Refactored code with trunk + Testing + Documentation

July 25 ~ August 15 [around 3 man week] - Implement mod_rewrite, reflect changes in php and js + Testing + Documentation

August 15 onwards - Compiling final report

Category (PHP, PELC, PEAR, other): PHP Manual