Hi,
Ok, since there seems to be controversy about how to best collaborate
on documents like TODO lists, RFC's, README's etc. and I do not want
to piss people of by making final decisions on this in a closed
circle. Here it goes. Honestly I do not think its a big issue either
way as long as we follow through with something. So please spare me an
endless discussion about nitty gritty. I want something done and I am
willing to put in the time. But I want the thing used if I do put in
the time. Also please no half hearted offers for help.
So here it goes.
===========
Current state:
===========
We currently have a a few outdated TODO files in cvs [1][2][3]. We
also have the unofficial todo wiki [4]. On that wiki we also have a
few other documents [5][6]. A few have been moved to php.net/reST
already, like the release process. Furthermore we have no real place
for RFC's to reside on php.net servers, so proposers have to use their
own servers [8]. Actually most of the time they simply just post to
the mailinglist and the only kind of summary of the discussions we get
are the Zend weeklies [9].
=======
Options:
=======
--------
I) Wiki
One option is to setup a wiki, the proposed choice was using dokuwiki,
which seems to support a flexibile auth system (so that we can use cvs
auth by default and fall back to a dokuwiki account for new guys that
do not yet have a cvs account), ACL's (so that we can control where
new guys can play around), namespaces (so that we can structure
related content), breadcrumb navigation, history/diffing. For a full
feature list look here [10]. Of course its PHP and OSS, so we can hack
on it as we please.
Work required:
# install dokuwiki
# setup an authentication service on master.php.net
# integrate authentication service with the wiki
# merge php-src TODO files with the todo items on my todo wiki
# migrate all relevant content to the wiki
# implement a proposal structure for RFC's along the lines of what
Lars has aleady proposed [11]
Advantages:
# easy to manage accounts for new guys
# wiki's are a fairly well established concept, even if the syntax
might be slightly different
# very little custom development needed
Disadvantages:
# interface is a browser for editing, diffing etc.
# separate application to maintain
---------
II) reST
We already have a way to render files straight out of CVS into happy
HTML. We are usign the reST [2] format for this. I did some work on
porting a few README's over to this format. Its not very hard albeit a
fairly boring job. We could expand this to also handle the TODO lists
quite easily. For the RFC's we could setup a new CVS repository and
simply render all RFC's via the current reST parser in a new location
(php.net/RFCs). Not sure how we would handle creation of other adhoc
documents [6].
Work required:
# merge php-src TODO files with the todo items on my todo wiki
# migrate all those todo's to reST format and commit them in the
proper branch, while removing the old TODO files
# expand the reST script to list/parse any file in some defined RFC
dir under a separate url (www.php.net/RFC?)
# talk to Rasmus to see about making it possible for more people to
open accounts
# tweak Lars's RFC template [11] to be reSTy
# determine where other documents [6] are supposed to go where people
want to collaborate on documents for php.net
Advantages:
# content is managed just like the rest of the source code
# reST is still fairly simple but much better tailored to handle the
needs for documentation
Disadvantages:
# new guys need to get a cvs.php.net account to be able to participate
and ACL system is not as finely grained as most wiki's are
# reST is not as widely known as wiki syntax
-----
III) write a reST "wiki" with a CVS storage backend
Essentially this is the reST proposal, but in order to get around the
issue of having to grant permissions, we could add an interface with a
separate auth layer and commits are done with a single user account
for those who do not have an account of their own. Note that II) can
be considered a stepping stone towards this solution. As such III)
could come later to solve some of the issues with II).
Advantages:
# easy to manage accounts for new guys
# people can pick and choose what they prefer .. local editor or web
interface
Disadvantages:
# more custom coding necessary
# reST is not as widely known as wiki syntax
-------
Personally I prefer going with a wiki, because I do not have much
affection with CVS for these kinds of documents (actually I do think
that the README's should be in CVS, which is why I worked with Hannes
on creating the current php.net/reST interface). I have put this
document up on my wiki [12], and I will keep it uptodate.
regards,
Lukas
[1] http://cvs.php.net/viewvc.cgi/php-src/TODO?view=markup
[2] http://cvs.php.net/viewvc.cgi/php-src/TODO-PHP5?view=markup
[3] http://cvs.php.net/viewvc.cgi/php-src/TODO-5.1?view=markup
[4] http://wiki.pooteeweet.org/PHPTODO/
[5] http://wiki.pooteeweet.org/MultiThreadedRunTests
[6] http://wiki.pooteeweet.org/TestFest
[7] http://ch2.php.net/reST/php-src/README.RELEASE_PROCESS
[8] http://www.stefan-marr.de/rfc-traits-for-php.txt
[9] http://devzone.zend.com/tag/Weekly_Summaries
[10] http://wiki.splitbrain.org/wiki%3Afeatures
[11] http://lars.schokokeks.org/php/php-rfc.txt
[12] http://wiki.pooteeweet.org/CollaborationToolchainRFC
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
