Re: Current state of my ideas on moving docs to GIT

Hi! what needs to be done for getting this actually being put in production? cheers, Derick On Sat, 4 Nov 2017, Andreas Heigl wrote: > Hey all! > > My apologies again for the previous mail: > > Now back to topic. > > What did I do so far to investigate ways of moving the PHP-Docs from SVN > to GIT: > > * I've pulled out the English Documentation from the SVN Repo using > git-svn and put it into it's own repo 'en'. > * I've created a hash-table that maps revision-number from SVN to GIT-HASHes > * I've pulled out the german documentation from the SVN-repo using > git-svn and put it into it'S own repo 'de'. > * I've pulled out the doc-base from the SVN-repo using git-svn and put > it into it's own repo 'doc-base' > * I've created a meta-repository with some scripts to automate things. > * I've created a script within that meta-repo to replace the > EN-Revision-Number within the 'de'-files (any translation file) with the > hash from the hash-table. That way the reference to the "revision" of > the base-file is kept. > * I've reworked the following scripts to not use SVN any more but to use GIT > * configure.php > * scripts/build-chms.php > * scripts/create-phpdoc-setup.php > * scripts/revcheck.php > * scripts/reviewedcheck.php > > For details on what exactly changed in these files have a look at > > https://github.com/phpdoctest/doc-base/compare/f71b7f2499fa7d897722f4a479bb1d0ecc9738a2...master > > The most important change probably is the revcheck.php-file. As the > en-repository and the de-repository are now two separate repositories I > needed to do some git-hacks to get the information about how many > commits there have been between the translated and the base file. And > there is definitely room for improvement! I'm looking forward to your ideas! > > > * I've created a Test-organization on github[1] to publish the stuff and > created the de-[2], en-[3] and doc-base[4] repositories in that. > * I've added travis-skripts to the de-[5] and the en-repos[6] that > automatically run the doc-base/configure.php and a full build of the > docs on each PR and Merge and can therefore test that everything works > as expected and nothing is broken. The script also publishes the built > docs after a merge to the repositories github-pages[7][8][9][10]. > > So so far we should be able to do all the things that need to be done to > translate the PHP-documentation and using GIT as a backend instead of SVN. > > I have no idea on what currently happens under the hood to actually > build the documentation from SVN and to distribute the build-artifacts > to the mirrors. Until now I didn't get any information about that. But > using the automation I introduced building the docs after a merge and > putting them somewhere they can then be distributed to the mirrors from > should not be an issue. > > My further approach would be to reach a decission on whether the way I > took is a feasible one and should be taken to the next step. That next > step would then be to reach a decission on the actual setup like using > git.php.net as primary or secondary server, use a publicly available and > much used frontend like github or gitlab to handle PullRequests, setup > something different, use automation tools or do manual labour etc etc. > > I would see this in an RFC like done for new features in the language > itself. Though I'm not sure the relevant people (maintainers of the > docs) actually have karma to vote on an RFC and whether non-docs > contributors should be able to vote on that RFC. > > So I would like your input on the following: > > * Is the way I took feasible? > * What did I miss? Especially which tools that I was not aware of that > are needed and where not touched? > * What happens currently behind the scenes to actually bring the > SVN-content onto the mirrors > * How shall we reach a decission on how to go on from here? Is an RFC > the right approach? Or is there some other form of finding a decission? > > I would like to move the discussion of the actual technical > implementation (git.php.net, github, gitlab, automation etc) to a later > stage as I think before we discuss the actuall HOW we should ind out > whether we want to go that way at all. So I'd see that discussion during > the "RFC-Phase" (however that is going to look like). > > Thanks for your time to read so far and your feedback. > > Cheers > > Andreas > > > [1] https://github.com/phpdoctest > [2] https://github.com/phpdoctest/de > [3] https://github.com/phpdoctest/en > [4] https://github.com/phpdoctest/doc-base > [5] https://github.com/phpdoctest/de/blob/master/.travis.yml > [6] https://github.com/phpdoctest/en/blob/master/.travis.yml > [7] https://phpdoctest.github.io/en/ > [8] https://phpdoctest.github.io/de/big-xhtml.html > [9] https://phpdoctest.github.io/de/chunked-xhtml/index.html > [10] https://phpdoctest.github.io/de/revcheck.html > -- https://derickrethans.nl | https://xdebug.org | https://dram.io Like Xdebug? Consider a donation: https://xdebug.org/donate.php twitter: @derickr and @xdebug