Re: PhD and Composer - 2020 approach in the no-mirror era

W dniu 19.04.2020 o 04:29, G. P. B. pisze:

On Sun, 19 Apr 2020 at 03:39, Maciej Sobaczewski <sobak@php.net <mailto:sobak@php.net>> wrote:

    Hello guys,

    long time no see, I know. A lot of things changed around us, I e.g. grew
    up to get my first actual job instead of studying and having way too
    much of a free time :D However, despite how it might look from outside
    I still haven't forgotten about php.net <http://php.net> nor my
    ideas to somehow improve
    its state.

    To the point - some of you may remember my move towards migrating PhD
    (PHP's manual builder) to use Composer. Actually, the implementation
    was ready even back then. It worked, I tested it locally multiple times.

    If my memory serves me right the main pain point back then was the
    amount of infrastructural changes it would require to make this move.

    I'm wondering if now, in 2020, COVID era when some people have a bit
    more time (or rather are forced to sit home and find something to do)
    we would be able to do something more about that. To make it happen.

    I'm not even sure about the infrastructure behind building the docs
    right now, AFAIR mirrors or CDN's don't have much to do with it since
    the docs have always been built on single machine and then rsynced to
    the mirrors, right? Has it changed?

    The implementation is right here
    https://github.com/php/phd/compare/master...Sobak:composer
    sitting and waiting to be finished. I'm absolutely willing to resolve
    any conflicts with current codebase, do some rebases to clean up the
    history etc. You can count on me when it comes to the code.

    The thing I would still need help with would be a cooperation in
    putting that on our servers network. If I'm correct that would mean
    the machine that builts the manual, the editor.php.net
    <http://editor.php.net> machine,
    Windows box that builds CHMs and perhaps euk2.php.net
    <http://euk2.php.net> responsible
    for docs.php.net <http://docs.php.net>

    I lost my access to the last one, which is rather understandable
    given all that time I was not responding etc. Either way, even
    with that access, I still wouldn't be able to finish the migration
    myself.

    Straight to the point. Are there people willing and capable of
    finishing the move? Is there even an interest in moving PhD to
    Composer? We still have "php" vendor name reserved by Packagist
    owners. The vendor which is still completely empty.

    I'm able to finish the code, bring it up to date and polish it
    within max a week, I think. Yet, without a cooperation it would
    still be a simple branch in the fork. Are there people willing
    to help me?

    To be completely fair, I would be more than grateful to finish
    this migration but I'm not going to put my time into polishing
    the code if it's going to stay unused. I absolutely don't want
    to put pressure on anyone as I have no intention and right to
    do so. I just want to be honest.

    I'm looking forward you answers and well, it's great to see you
    again, everyone!

    Maciej Sobaczewski

    PS: I allowed myself to CC the most influencial and active people
    out there (at least the ones that were active during "my times".)
    I hope that you do not take the offence.

Hello Maciej,

Hi George :) It's nice to meet you and see response so quickly.

I don't know much about the infra, but with the migration from SVN to Git I'd imagine that the online editor would stop working and would be discontinued. I also needed to look up what CHM is, and are these still being built? IIRC the PDF versions of the manual stopped being built a while ago.

The CHM (Help format form Microsoft) is definitely being built and oferred to download[1]. It used to work surprisingly well when I last used it and above all I don't want to make any functional changes to PhD, at least not now. Let's focus on one thing at a time.

I know this is a tangent but a couple of month ago I tried to play around using pandoc [1] to generate the docs instead oh PhD and it failed pretty bad as the manual generated by the build uses XML system entities which pandoc does not support.

I don't know what happened that the PDF builds are not longer generated but are you sure that it's because PhD _can't_ build them anymore or we just stopped using it for building them for some reason. I suppose it's the former.

What I'm trying to bring forward is that maybe we should look into refactoring the whole build process so that we can have a build which doesn't take so much time that we only build the docs and published them once a day.

I don't know where did you get info about docs being built once a day but if it was on doc.php.net/tutorial/ then it was me who wrote that information :D and while it was true at the time I'm not sure if it's still that way. Either way, even if we are building manual once a day it's more for the reasons other than technical. We have special docs.php.net mirror that builds six times a day and does so for much more language versions than php.net. Its purpose mainly to being able to test changes in the live environment before they go to everyone. Hence, rarer builds on php.net. Building English manual (definitely the biggest language version) takes around 6 minutes on my not really beefy PC. There is definitely some room for improvements in PhD, like in every other software but it's extremely well thought-out and flexible system that is able to handle our custom markup here and there and generate many many formats in reasonable time.

Altoutgh this is not what you're are asking, I think it's something to consider instead of, maybe, spending time on moving PhD to composer.

I might be wrong but I'm pretty sure that time spent on PhD refactoring would be a magnitude greater than finishing the move to Composer. And then, of course, we can go further and look for possible improvements in other areas. I have some on my mind already :)

Anyway, the effort is highly appreciated from me :) Best regards George P. Banyard

Thanks! Maciej

[1] https://pandoc.org/

[1]: https://www.php.net/download-docs.php