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 <[email protected] 
> <mailto:[email protected]>> 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