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

Hi Andreas and doc geeks, On 4 November 2017 at 14:46, Andreas Heigl <andreas@heigl.org> 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.. > Thank you for putting in all of this work. Let's run ahead with this experiment and see how it goes. > > 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. As far as I'm aware, the information on http://doc.php.net/tutorial/builds.php is still correct. The rsync server is the one that regularly pulls from SVN and uses PhD to build all of the "active" languages. The build results are placed in a location that the php.net website mirrors then rsync from. The scripts for all of that can be found in our "systems" Git repo at http://git.php.net/?p=systems.git;a=tree;f=rsync.php.net > 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. > Agreed. > > 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. Let's give it a go and see how it works in practice. > That next > step would then be to reach a decission on the actual setup like using > git.php.net as primary or secondary server, My preference is to have git.php.net be the canonical repo host with GitHub as only a mirror for the source. This way, we can keep using existing tooling (such as the commit karma checking). That said, I'm not a dictator so if there are good reasons, or strong consensus, not to do the above then I am all ears. > 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. > At this stage, I don't really mind if there are more "manual labour" steps than automated ones. Things like automated build-on-merge tasks can come later (the cron job builds work fine, for now). > > I would see this in an RFC like done for new features in the language > itself. I'm not sure. I can envision folks liking the idea of having an RFC. However, I think that we as a team can make this work without waiting for the mostly symbolic "OK" from the wider PHP audience. > 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. > Anyone with a @php.net account can vote on any RFC. It does not matter what commit karma (if any) that person has. > > So I would like your input on the following: > > * Is the way I took feasible? > Yes. > * What did I miss? Especially which tools that I was not aware of that > are needed and where not touched? I'm sure there are things being missed, this will always be the case. :) > * What happens currently behind the scenes to actually bring the > SVN-content onto the mirrors > See above, regarding the rsync machine. > * 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? > An RFC might be useful, more for having everything down on paper than for the approval vote. But I would advise putting time and energy in to pushing ahead and actually trying this out to see if it is going to work. > > 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). > We want to be using Git. So let's make that happen. > > 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 > -- > ,,, > (o o) > +---------------------------------------------------------ooO-(_)-Ooo-+ > | Andreas Heigl | > | mailto:andreas@heigl.org N > 50°22'59.5" E 08°23'58" | > | http://andreas.heigl.org ¸i!H‹ê²cµû > Ê‚http://hei.gl/wiFKy7 | > +---------------------------------------------------------------------+ > | http://hei.gl/root-ca > | > +---------------------------------------------------------------------+ >