Re: Moving documentation to Git

Hi Peter, Hi All, Am 09.10.17 um 16:45 schrieb Peter Cowburn: > On 9 October 2017 at 15:13, Andreas Heigl <andreas@heigl.org> wrote: > >> Hi Peter. >> >> Am 09.10.2017 um 14:58 schrieb Peter Kokot <peterkokot@gmail.com>: >> >> Hello, >> >> Is there any realistic option that PHP will have documentation editable >> also via pull requests over GitHub in the near future? >> >> >> I‘ve started moving the docs over to git earlier this year and created a >> test-repo on github (https://github.com/phpdoctest). Due to less free >> time not much happened in the last two or three months. And some things >> still need to be decided upon like where to host the repo (git.php.net, >> gitlab, github...) and depending on that how the workflows are. >> > > The only choice here is git.php.net for the centralized location. We can > (and hopefully will) mirror to GitHub as well, just like many of the other > Git repos we have. I'm very bisased by that. On the one hand I would see it that way and it makes absolutely sense. But on the other hand I see some disadvantages in that approach not due to the central git-repo but due to the missing infrastructure around the git-repos. In these days people expect more from moving to git than a git repo instead of an svn one. If it's only about moving from one VCS to another one we have to ask ourselves why we want to do it. Just because SVN isn't the cool kid anymore? Nowadays a git based source-control allows so much more like easier automation of tasks especially in a Pull/Merge-Request based workflow. Interaction based on Pull- or Merge-Requests makes collaboration so much easier. But most of the developers these days would also expect a way to do code-reviews on these Requests. And forwarding a DIFF via email is technically perfectly OK but well… So for me moving the PHP-Docs from SVN to GIT also means shifting from a workflow where only a few had access to the repository and getting a change into the documentation from a non-regular contributor meant a lot of tedious work and relying on the time of someone (who often wasn't actually known) to get the changes you did on edit.php.net actually into the sources. And when that eventually happened you might not wven know about that. In a more modern workflow - and that's more or less what we know from github - I'm able to spot an issue in the docs, head over to the web-frontent of the repo (probably by a link on the docs-page itself) propose a change of the docs by a pull- or merge-request and get notified when someone merges it into the master branch. Apart from that I don't need to setup the whole environment myself to verify the Request is valid but the underlying CI-system picks up the request, runs some tests on it and marks them as faulty or valid. And last not least the people responsible for the repository are known and can be addressed directly should a PR be in the pipeline for too long (however that might be defined (-; ) So I have no issues with moving the repository over to git.php.net. But I'd recommend we should then also think about a ci.php.net (or jenkins.php.net or whatever) and a gitlab.php.net (or whatever decent webinterface we would like to use). And before that happens, why not use github or gitlab as the main repository and use a trigger to replicate the changes to git.php.net… Yes, the php-karma would suddenly not work any more for the docs. But is that really an issue? Both backends allow people to be added to groups that have certain access rights to the repositories. Isn't that fine as well? In my eyes having a solution that is open for as many contributors to contribute easily is to favour over a solution that hinders collaboration and causes people to not help out. Personally I would like to have an RFC about how to do things. > > >> >> Currently the docs are (should be) built on every push to master of the >> language-branch. They are reachable via github-pages though ATM I don‘t >> have a working link at hand. >> > > It looks like the English version is available at > https://phpdoctest.github.io/en/ The german version is the more "advanced" one, that has the revision-check document at https://phpdoctest.github.io/de/revcheck.html and the chunked HTML-Docs at https://phpdoctest.github.io/de/chunked-xhtml/index.html Both are created on every merge to master using travis' deploy-features. I didn't (yet) get round to create an index.html that gives you the options… > Cheers Andreas -- ,,, (o o) +---------------------------------------------------------ooO-(_)-Ooo-+ | Andreas Heigl | | mailto:andreas@heigl.org N 50°22'59.5" E 08°23'58" | | http://andreas.heigl.org http://hei.gl/wiFKy7 | +---------------------------------------------------------------------+ | http://hei.gl/root-ca | +---------------------------------------------------------------------+

Attachment: [application/pgp-keys] 0x5BFCE472.asc
Attachment: [application/pgp-signature] OpenPGP digital signature signature.asc