[PHP-DEV] RFC: documentation collaboration toolchain

[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

[Pierre Joye]

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.

I'd go for RFC in CVS/Rest, and the todo's in a wiki.

Limiting the RFC to existing php.net's member sound like a bad idea
and create CVS accounts only for a RFC does not sound any better.

I would rather use the wiki for the complete process. Once a RFC
reached a "stable" status, we can add it to a RFC repository.

VC are perfect for source codes and relatively static contents but nor
for documents edition like what we need for RFC, todos or other
similar documents (no source code).

Cheers,

[Derick Rethans]

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.

I'd go for RFC in CVS/Rest, and the todo's in a wiki.

regards,
Derick

[Stefan Marr]

Post by Pierre Joye
Limiting the RFC to existing php.net's member sound like a bad idea
and create CVS accounts only for a RFC does not sound any better.
I would rather use the wiki for the complete process. Once a RFC
reached a "stable" status, we can add it to a RFC repository.

Would agree on this. For me at would have been a burden to get such an
account upfront. Since I'm not part of the core dev team.

Kind Regards
Stefan

[Lukas Kahwe Smith]

Post by Stefan Marr

Post by Pierre Joye
Limiting the RFC to existing php.net's member sound like a bad idea
and create CVS accounts only for a RFC does not sound any better.
I would rather use the wiki for the complete process. Once a RFC
reached a "stable" status, we can add it to a RFC repository.

Would agree on this. For me at would have been a burden to get such
an account upfront. Since I'm not part of the core dev team.

I will try and look if I can make dokuwiki work using a reST syntax
and CVS as storage (this is possible since dokuwiki stores all content
as plain text files with no additional metadata). Anyone willing to
help please email me offlist as I do not think that this should clog
up this mailinglist. But let me briefly detail what I would want to do
(feel free to also email me offlist that I am an idiot for trying this
and why you think so):

1) Authentication is done against master.php.net, but falls back to a
dokuwiki db, but only if the provided username does not exist in
master.php.net to prevent people from "highjacking" a CVS account name
on the wiki. This authentication interface does not yet exist on
master.php.net and Hannes tentatively agreed to implement it.

2) Edits on the web interface will commit to CVS. In a first step I
would use a single user, eventually I might try to look into
committing as a specific user if the wiki user was authenticated via
master.php.net, but there are of course (solveable) security
implications here (until then people with a CVS account should use
that to ensure proper log history). Note that dokuwiki supports an
"optimistic locking" approach, where it allows you to manually resolve
a conflict (diff provided) when someone does a change in between
opening the edit form and submitting. This is of course important
since CVS commits can not be protected by "pessimistic locks" that
dokuwiki also supports.

3) Now on the CVS side I would say we should have a new repository. I
would need to implement some post commit hooks that will leverage the
dokuwiki CLI interface to ensure that meta data is updated
accordingly. Open question is if its even possible to have a post
commit hook specifically for just one CVS repo.

In the end it should however be possible for people to edit files
inside CVS without ever doing anything with the web interface. On the
web interface side the only thing will be that CVS users will by pass
the "pessimistic locking" (maybe we will just disable it for
consistency .. I prefer optimistic locking anyways). Also we still
have the ability of providing any content on the wiki along the lines
of what we have with php.net/reST at the moment. On top of that we can
grant people access to the wiki (or parts of the wiki) without much
hesitation. As a result we could even provide the accounts for RFC's
maybe even via an automated process. Commits of these people will of
course be done with a standard user account, so the history on the
wiki will be the only way to tell who did what. This is obviously
"solveable" by given that person a CVS account quickly.

regards,
Lukas

[Marcus Boerger]

Hello Lukas,

Post by Pierre Joye

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.

I'd go for RFC in CVS/Rest, and the todo's in a wiki.

Limiting the RFC to existing php.net's member sound like a bad idea
and create CVS accounts only for a RFC does not sound any better.
I would rather use the wiki for the complete process. Once a RFC
reached a "stable" status, we can add it to a RFC repository.
VC are perfect for source codes and relatively static contents but nor
for documents edition like what we need for RFC, todos or other
similar documents (no source code).

We should have all such docs on a WiKi with ACLs reflecting CVS accounts
and additional WiKi specific accounts. As Pierre points out correctly,
having to give every newcomer for every idea a CVS Access is pretty bad.
Maybe the bast way to do it is to control that by our user database. Very
easy, or is this too easy?

Best regards,
Marcus

[Stanislav Malyshev]

Hi!

Post by Lukas Kahwe Smith
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.

I'm for using wiki for brainstorm-stage projects - basically anybody
with a crazy idea backed by some explanations, examples, etc. should be
able to place it into the wiki and have it there for discussion. There
should be very relaxed procedure on giving auth there - basically
anybody who's not a troll or a bot should be able to play :)

For projects that are in more "accepted" state - i.e. ones that we know
we want to do in PHP and have good idea how, or TODO items that are
agreed upon and just waiting for people to take care of them - CVS-based
system like reST sounds better. These docs would be mostly static and
for informational purposes - like NEWS etc. Current CVS accounts would
be enough for those, since people that have reason to edit them probably
would be people already holding CVS account anyway.