# RFC: documentation collaboration toolchain - Thread: https://externals.io/message/35750 - Original archive: https://news-web.php.net/php.internals/35750 - Started by Lukas Kahwe Smith on 2008-02-23T14:29:37+00:00 - Messages: 7 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #35750 — Lukas Kahwe Smith — 2008-02-23T14:29:37+00:00 URL: https://externals.io/message/35750#35750 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 --- ## #35793 — Derick Rethans — 2008-02-25T14:59:07+00:00 URL: https://externals.io/message/35750#35793 · In reply to: #35750 > 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 -- Derick Rethans http://derickrethans.nl | http://ezcomponents.org | http://xdebug.org --- ## #35794 — Pierre Joye — 2008-02-25T16:04:45+00:00 URL: https://externals.io/message/35750#35794 · In reply to: #35793 > > > > […] > > 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, -- Pierre http://blog.thepimp.net | http://www.libgd.org --- ## #35796 — Stefan Marr — 2008-02-25T16:20:18+00:00 URL: https://externals.io/message/35750#35796 · In reply to: #35794 Pierre Joye schrieb: > 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 --- ## #35808 — Lukas Kahwe Smith — 2008-02-26T19:48:07+00:00 URL: https://externals.io/message/35750#35808 · In reply to: #35796 > Pierre Joye schrieb: > > […] > 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 --- ## #35849 — Marcus Boerger — 2008-02-28T14:30:37+00:00 URL: https://externals.io/message/35750#35849 · In reply to: #35794 Hello Lukas, Monday, February 25, 2008, 5:04:45 PM, Pierre wrote: > > > […] > 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 --- ## #35866 — Stanislav Malyshev — 2008-02-29T18:27:26+00:00 URL: https://externals.io/message/35750#35866 · In reply to: #35750 Hi! > 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. -- Stanislav Malyshev, Zend Software Architect stas@zend.com http://www.zend.com/ (408)253-8829 MSN: stas@zend.com