Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:35750
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain pooteeweet.org from 85.10.196.195 cause and error)
Message-ID: <0F1A0758-D3AF-4B1C-B2E0-7BEEEE1ED2C6@pooteeweet.org>
To: PHP Developers Mailing List <internals@lists.php.net>
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v919.2)
Date: Sat, 23 Feb 2008 15:29:37 +0100
X-backendmedia-com-MailScanner-Information: Please contact the ISP for more information
X-backendmedia-com-MailScanner: Found to be clean
X-backendmedia-com-MailScanner-SpamCheck: not spam, SpamAssassin (not cached,
	score=0.132, required 6, AWL 0.03, RDNS_DYNAMIC 0.10)
X-backendmedia-com-MailScanner-From: mls@pooteeweet.org
X-Spam-Status: No
Subject: RFC: documentation collaboration toolchain
From: mls@pooteeweet.org (Lukas Kahwe Smith)

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