Moving the documentation to git

php.internals

Andreas Heigl

6 years ago
Hey folks. During the last year I took a bit of time aside to bring the documentation from SVN to git. And about a month ago I informed the DOCs-Mailinglist about the current status and the fact that we are ready to move to the next step[1]. Now some tasks need to be done by people with appropriate karma to be able to get on with the whole thing, but all the background tasks are done and awaiting further processing. Sadly there was no response so far. Neither on the email as such nor on the different tasks. So the main question is now, how the PHP-Project wants to go on with moving the documentation from SVN to git? Is there any interest in continuing this project? And if so, who can either take on the necessary steps or provide us with the appropriate credentials and access rights that we can do them ourselves? Thanks for reading and looking forward to the results. Cheers Andreas [https://news-web.php.net/php.doc/969387429]
-- ,,, (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 | +---------------------------------------------------------------------+

Benjamin Morel

6 years ago
> > So the main question is now, how the PHP-Project wants to go on with > moving the documentation from SVN to git? Is there any interest in > continuing this project?
Yes please. I would contribute a thousand times more if I could just make PRs on GitHub. Right now I'm being put off by the documentation editor. — Benjamin

Derick Rethans

6 years ago
On Tue, 4 Feb 2020, Andreas Heigl wrote:
> Sadly there was no response so far. Neither on the email as such nor on > the different tasks.
Keep repeating them and poking the people. I have most definitely forgotten about what needs doing. cheers, Derick
-- PHP 7.4 Release Manager Host of PHP Internals News: https://phpinternals.news Like Xdebug? Become my Patron: https://www.patreon.com/derickr https://derickrethans.nl | https://xdebug.org | https://dram.io twitter: @derickr and @xdebug

Nikita Popov

6 years ago
On Tue, Feb 4, 2020 at 8:09 AM Andreas Heigl <andreas@heigl.org> wrote:
> Hey folks. > > During the last year I took a bit of time aside to bring the > documentation from SVN to git. And about a month ago I informed the > DOCs-Mailinglist about the current status and the fact that we are ready > to move to the next step[1]. Now some tasks need to be done by people > with appropriate karma to be able to get on with the whole thing, but > all the background tasks are done and awaiting further processing. > > Sadly there was no response so far. Neither on the email as such nor on > the different tasks. > > So the main question is now, how the PHP-Project wants to go on with > moving the documentation from SVN to git? Is there any interest in > continuing this project? And if so, who can either take on the necessary > steps or provide us with the appropriate credentials and access rights > that we can do them ourselves? > > Thanks for reading and looking forward to the results. > > Cheers > > Andreas > > [https://news-web.php.net/php.doc/969387429] >
Hi Andreas, would you mind pushing the current en/de repos to https://github.com/phpdoctest/en and de so it's possible to see how they look like now? Nikita

Andreas Heigl

6 years ago
Hey Nikita, hey all. Am 04.02.20 um 12:11 schrieb Nikita Popov:
> On Tue, Feb 4, 2020 at 8:09 AM Andreas Heigl <andreas@heigl.org > <mailto:andreas@heigl.org>> wrote:
> > Hi Andreas, > > would you mind pushing the current en/de repos to > https://github.com/phpdoctest/en and de so it's possible to see how they > look like now?
Find the repos (as they should be on git.php.net would I have access) at https://github.com/phpdoctest/de and https://github.com/phpdoctest/en They are updated after each run of the converter-tool which currently runs every two hours. 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 | +---------------------------------------------------------------------+

Nikita Popov

6 years ago
On Tue, Feb 4, 2020 at 1:48 PM Andreas Heigl <andreas@heigl.org> wrote:
> Hey Nikita, hey all. > > Am 04.02.20 um 12:11 schrieb Nikita Popov: > > On Tue, Feb 4, 2020 at 8:09 AM Andreas Heigl <andreas@heigl.org > > <mailto:andreas@heigl.org>> wrote: > > > > > Hi Andreas, > > > > would you mind pushing the current en/de repos to > > https://github.com/phpdoctest/en and de so it's possible to see how they > > look like now? > > Find the repos (as they should be on git.php.net would I have access) at > https://github.com/phpdoctest/de and https://github.com/phpdoctest/en > > They are updated after each run of the converter-tool which currently > runs every two hours. >
Thanks! It looks like currently the author mapping from svn -> git is missing, which also means we don't get the mapping to github accounts. I'll send you the author mapping file I have (which is unfortunately somewhat dated, maybe Peter has a newer one?), it would be great to preserve authorship in a meaningful way. Nikita

Nikita Popov

6 years ago
On Tue, Feb 4, 2020 at 2:08 PM Nikita Popov <nikita.ppv@gmail.com> wrote:
> On Tue, Feb 4, 2020 at 1:48 PM Andreas Heigl <andreas@heigl.org> wrote: > >> Hey Nikita, hey all. >> >> Am 04.02.20 um 12:11 schrieb Nikita Popov: >> > On Tue, Feb 4, 2020 at 8:09 AM Andreas Heigl <andreas@heigl.org >> > <mailto:andreas@heigl.org>> wrote: >> >> > >> > Hi Andreas, >> > >> > would you mind pushing the current en/de repos to >> > https://github.com/phpdoctest/en and de so it's possible to see how >> they >> > look like now? >> >> Find the repos (as they should be on git.php.net would I have access) at >> https://github.com/phpdoctest/de and https://github.com/phpdoctest/en >> >> They are updated after each run of the converter-tool which currently >> runs every two hours. >> > > Thanks! It looks like currently the author mapping from svn -> git is > missing, which also means we don't get the mapping to github accounts. I'll > send you the author mapping file I have (which is unfortunately somewhat > dated, maybe Peter has a newer one?), it would be great to preserve > authorship in a meaningful way. > > Nikita >
In a previous mail you mentioned that the current EN-Revision is now being tracked in a separate file. Could you point out which files that is, because I didn't see it in the repo. Or is it part of some other repo? Nikita

Andreas Heigl

6 years ago
Hey Nikita. Am 04.02.20 um 15:20 schrieb Nikita Popov:
> On Tue, Feb 4, 2020 at 2:08 PM Nikita Popov <nikita.ppv@gmail.com> wrote: > >> On Tue, Feb 4, 2020 at 1:48 PM Andreas Heigl <andreas@heigl.org> wrote: >> >>> Hey Nikita, hey all. >>> >>> Am 04.02.20 um 12:11 schrieb Nikita Popov: >>>> On Tue, Feb 4, 2020 at 8:09 AM Andreas Heigl <andreas@heigl.org >>>> <mailto:andreas@heigl.org>> wrote: >>> >>>> >>>> Hi Andreas, >>>> >>>> would you mind pushing the current en/de repos to >>>> https://github.com/phpdoctest/en and de so it's possible to see how >>> they >>>> look like now? >>> >>> Find the repos (as they should be on git.php.net would I have access) at >>> https://github.com/phpdoctest/de and https://github.com/phpdoctest/en >>> >>> They are updated after each run of the converter-tool which currently >>> runs every two hours. >>> >> >> Thanks! It looks like currently the author mapping from svn -> git is >> missing, which also means we don't get the mapping to github accounts. I'll >> send you the author mapping file I have (which is unfortunately somewhat >> dated, maybe Peter has a newer one?), it would be great to preserve >> authorship in a meaningful way. >> >> Nikita >> > > In a previous mail you mentioned that the current EN-Revision is now being > tracked in a separate file. Could you point out which files that is, > because I didn't see it in the repo. Or is it part of some other repo?
The en-revision is tracked in the translated repos only, not in the english one. Have a look at https://github.com/phpdoctest/de/blob/master/.en-revisions.ref 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 | +---------------------------------------------------------------------+

Nikita Popov

6 years ago
On Tue, Feb 4, 2020 at 3:46 PM Andreas Heigl <andreas@heigl.org> wrote:
> Hey Nikita. > > Am 04.02.20 um 15:20 schrieb Nikita Popov: > > On Tue, Feb 4, 2020 at 2:08 PM Nikita Popov <nikita.ppv@gmail.com> > wrote: > > > >> On Tue, Feb 4, 2020 at 1:48 PM Andreas Heigl <andreas@heigl.org> wrote: > >> > >>> Hey Nikita, hey all. > >>> > >>> Am 04.02.20 um 12:11 schrieb Nikita Popov: > >>>> On Tue, Feb 4, 2020 at 8:09 AM Andreas Heigl <andreas@heigl.org > >>>> <mailto:andreas@heigl.org>> wrote: > >>> > >>>> > >>>> Hi Andreas, > >>>> > >>>> would you mind pushing the current en/de repos to > >>>> https://github.com/phpdoctest/en and de so it's possible to see how > >>> they > >>>> look like now? > >>> > >>> Find the repos (as they should be on git.php.net would I have access) > at > >>> https://github.com/phpdoctest/de and https://github.com/phpdoctest/en > >>> > >>> They are updated after each run of the converter-tool which currently > >>> runs every two hours. > >>> > >> > >> Thanks! It looks like currently the author mapping from svn -> git is > >> missing, which also means we don't get the mapping to github accounts. > I'll > >> send you the author mapping file I have (which is unfortunately > somewhat > >> dated, maybe Peter has a newer one?), it would be great to preserve > >> authorship in a meaningful way. > >> > >> Nikita > >> > > > > In a previous mail you mentioned that the current EN-Revision is now > being > > tracked in a separate file. Could you point out which files that is, > > because I didn't see it in the repo. Or is it part of some other repo? > > The en-revision is tracked in the translated repos only, not in the > english one. > > Have a look at > https://github.com/phpdoctest/de/blob/master/.en-revisions.ref
Thanks! I think what confused me is that the last commit to the repo ( https://github.com/phpdoctest/de/commit/10286e6f55405503cecfeae2e91fa030a57a5906) modifies an EN-Revision in a file, but there is no corresponding update to .en-revisions.ref. Shouldn't there be one? PS: I have done "Step 1" and created all the necessary repositories in git.php.net. Nikita

Andreas Heigl

6 years ago
Hey Nikita. Am 04.02.20 um 15:49 schrieb Nikita Popov:
> On Tue, Feb 4, 2020 at 3:46 PM Andreas Heigl <andreas@heigl.org> wrote: > >> Hey Nikita. >> >> Am 04.02.20 um 15:20 schrieb Nikita Popov: >>> On Tue, Feb 4, 2020 at 2:08 PM Nikita Popov <nikita.ppv@gmail.com> >> wrote: >>> >>>> On Tue, Feb 4, 2020 at 1:48 PM Andreas Heigl <andreas@heigl.org> wrote: >>>> >>>>> Hey Nikita, hey all. >>>>> >>>>> Am 04.02.20 um 12:11 schrieb Nikita Popov: >>>>>> On Tue, Feb 4, 2020 at 8:09 AM Andreas Heigl <andreas@heigl.org >>>>>> <mailto:andreas@heigl.org>> wrote: >>>>> >>>>>> >>>>>> Hi Andreas, >>>>>> >>>>>> would you mind pushing the current en/de repos to >>>>>> https://github.com/phpdoctest/en and de so it's possible to see how >>>>> they >>>>>> look like now? >>>>> >>>>> Find the repos (as they should be on git.php.net would I have access) >> at >>>>> https://github.com/phpdoctest/de and https://github.com/phpdoctest/en >>>>> >>>>> They are updated after each run of the converter-tool which currently >>>>> runs every two hours. >>>>> >>>> >>>> Thanks! It looks like currently the author mapping from svn -> git is >>>> missing, which also means we don't get the mapping to github accounts. >> I'll >>>> send you the author mapping file I have (which is unfortunately >> somewhat >>>> dated, maybe Peter has a newer one?), it would be great to preserve >>>> authorship in a meaningful way. >>>> >>>> Nikita >>>> >>> >>> In a previous mail you mentioned that the current EN-Revision is now >> being >>> tracked in a separate file. Could you point out which files that is, >>> because I didn't see it in the repo. Or is it part of some other repo? >> >> The en-revision is tracked in the translated repos only, not in the >> english one. >> >> Have a look at >> https://github.com/phpdoctest/de/blob/master/.en-revisions.ref > > > Thanks! I think what confused me is that the last commit to the repo ( > https://github.com/phpdoctest/de/commit/10286e6f55405503cecfeae2e91fa030a57a5906) > modifies an EN-Revision in a file, but there is no corresponding update to > .en-revisions.ref. Shouldn't there be one?
There should be one and I have noticed that as well. I will need to redo the steps anyhow this weekend to add the correct authors-file and will then also have a look at why that is not updated accordingly. Do you know which file that update was in?
> > PS: I have done "Step 1" and created all the necessary repositories in > git.php.net.
Awesome! Thank you! Who has commit access to that repo so far? I would then start pushing the data as soon as I have fixed the authors list. At least to the translations. @salathe, shall I also force-push to the neglish master-branch or shall I push to a different branch in the en-repo? Cheers Andreas
> > Nikita >
-- ,,, (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 | +---------------------------------------------------------------------+

Nikita Popov

6 years ago
On Tue, Feb 4, 2020 at 3:55 PM Andreas Heigl <andreas@heigl.org> wrote:
> Hey Nikita. > > Am 04.02.20 um 15:49 schrieb Nikita Popov: > > On Tue, Feb 4, 2020 at 3:46 PM Andreas Heigl <andreas@heigl.org> wrote: > > > >> Hey Nikita. > >> > >> Am 04.02.20 um 15:20 schrieb Nikita Popov: > >>> On Tue, Feb 4, 2020 at 2:08 PM Nikita Popov <nikita.ppv@gmail.com> > >> wrote: > >>> > >>>> On Tue, Feb 4, 2020 at 1:48 PM Andreas Heigl <andreas@heigl.org> > wrote: > >>>> > >>>>> Hey Nikita, hey all. > >>>>> > >>>>> Am 04.02.20 um 12:11 schrieb Nikita Popov: > >>>>>> On Tue, Feb 4, 2020 at 8:09 AM Andreas Heigl <andreas@heigl.org > >>>>>> <mailto:andreas@heigl.org>> wrote: > >>>>> > >>>>>> > >>>>>> Hi Andreas, > >>>>>> > >>>>>> would you mind pushing the current en/de repos to > >>>>>> https://github.com/phpdoctest/en and de so it's possible to see how > >>>>> they > >>>>>> look like now? > >>>>> > >>>>> Find the repos (as they should be on git.php.net would I have > access) > >> at > >>>>> https://github.com/phpdoctest/de and > https://github.com/phpdoctest/en > >>>>> > >>>>> They are updated after each run of the converter-tool which currently > >>>>> runs every two hours. > >>>>> > >>>> > >>>> Thanks! It looks like currently the author mapping from svn -> git is > >>>> missing, which also means we don't get the mapping to github accounts. > >> I'll > >>>> send you the author mapping file I have (which is unfortunately > >> somewhat > >>>> dated, maybe Peter has a newer one?), it would be great to preserve > >>>> authorship in a meaningful way. > >>>> > >>>> Nikita > >>>> > >>> > >>> In a previous mail you mentioned that the current EN-Revision is now > >> being > >>> tracked in a separate file. Could you point out which files that is, > >>> because I didn't see it in the repo. Or is it part of some other repo? > >> > >> The en-revision is tracked in the translated repos only, not in the > >> english one. > >> > >> Have a look at > >> https://github.com/phpdoctest/de/blob/master/.en-revisions.ref > > > > > > Thanks! I think what confused me is that the last commit to the repo ( > > > https://github.com/phpdoctest/de/commit/10286e6f55405503cecfeae2e91fa030a57a5906 > ) > > modifies an EN-Revision in a file, but there is no corresponding update > to > > .en-revisions.ref. Shouldn't there be one? > > There should be one and I have noticed that as well. I will need to redo > the steps anyhow this weekend to add the correct authors-file and will > then also have a look at why that is not updated accordingly. Do you > know which file that update was in? >
Sorry, not sure what you mean by "which file" here.
> > > > PS: I have done "Step 1" and created all the necessary repositories in > > git.php.net. > > Awesome! Thank you! Who has commit access to that repo so far? I would > then start pushing the data as soon as I have fixed the authors list. At > least to the translations.
I have granted you access to the new repositories (force push should also work -- we don't disable that by default). That is everything apart from doc/base, doc/en and doc/de, because Peter is currently mirroring those. You'll have to coordinate with him to avoid two different mirroring setups overwriting each other.
> @salathe, shall I also force-push to the > neglish master-branch or shall I push to a different branch in the en-repo? >
Once the author list is fixed, are those repositories actually going to differ in any way? As far as I understood, only the translation repos are changed. Assuming your mirroring methodology is the same, I would expect you to arrive at the same doc-en repo. Nikita

Andreas Heigl

6 years ago
Hey Internals and docs-folks On Monday we finished the first important step of moving the documentation to git. Nikita created all the missing repos and Peter provided me with push access to all those repos via the phpdocbot account. I then cloned all currently active language-repos using an authors map from SVn to git and pushed the result to git.php.net/doc. Now the docs are continuously fetched from SVN, converted to git and pushed to their respective repos. The english docs every 15 minutes and the translations every two hours. Currently the leading system (the Single Source Of Truth) is still SVN! But people can now already contribute via git to the docs as – at least as far as I understood – the process of pushing changes from git to SVN is more or less automated (correct me if I'm wrong here, Nikita/Peter). Now the next steps are to move the toolage from SVN to git. That means: * Switch Source Retrieval for Docs building on docs.php.net from svn.php.net to git.php.net * Switch Generation of revcheck-files from svn to git (Work is already done at https://github.com/phpdoctest/doc-base/blob/master/scripts/revcheck.php) * Verify that everything works as expected When that is finished and accepted we can move over to the next stage: * Switch Source Retrieval for Docs building on rsynv.php.net from SVN to git * Setup Mirroring and processes to merge PRs from GitHub to documentation git. * Rewrite setup-instructions and send email to docs team regarding new process And then we can finally make SVN readonly. (and the cronjobs on svngit.php.net need top be shut down) I've also added the ToDo list to https://github.com/phpdoctest/meta/wiki/todo, so that everyone can follow the process. As the next steps need access to euk2.php.net which I currently do not have, I'd need someone to actually do those next tasks. Access – according to the wiki – have bjori, mgdm, mj, nilgun, philip, salathe, sobak, tyrael and yannick. I'd be very happy if one of you could ping me so that we can check the next steps. Thank you all for the support during the last weeks. Cheers Andreas Am 04.02.20 um 08:09 schrieb Andreas Heigl:
> Hey folks. > > During the last year I took a bit of time aside to bring the > documentation from SVN to git. And about a month ago I informed the > DOCs-Mailinglist about the current status and the fact that we are ready > to move to the next step[1]. Now some tasks need to be done by people > with appropriate karma to be able to get on with the whole thing, but > all the background tasks are done and awaiting further processing. > > Sadly there was no response so far. Neither on the email as such nor on > the different tasks. > > So the main question is now, how the PHP-Project wants to go on with > moving the documentation from SVN to git? Is there any interest in > continuing this project? And if so, who can either take on the necessary > steps or provide us with the appropriate credentials and access rights > that we can do them ourselves? > > Thanks for reading and looking forward to the results. > > Cheers > > Andreas > > [https://news-web.php.net/php.doc/969387429] >
-- ,,, (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 | +---------------------------------------------------------------------+

Unnamed Person

6 years ago
Hello Andreas,
> But people can now already contribute via git to the docs as – at least
Does that mean that we can skip the (inaccessible) edit.php.net and send pull requests on Github? Thanks!
-- With best regards from Germany, Andre Skype: menelion_elensule Twitter (English only): @AndrePolykanine ------------ Original message ------------ From: Andreas Heigl <andreas@heigl.org> To: internals@lists.php.net Date created: , 7:31:17 AM Subject: Moving the documentation to git Hey Internals and docs-folks On Monday we finished the first important step of moving the documentation to git. Nikita created all the missing repos and Peter provided me with push access to all those repos via the phpdocbot account. I then cloned all currently active language-repos using an authors map from SVn to git and pushed the result to git.php.net/doc. Now the docs are continuously fetched from SVN, converted to git and pushed to their respective repos. The english docs every 15 minutes and the translations every two hours. Currently the leading system (the Single Source Of Truth) is still SVN! But people can now already contribute via git to the docs as – at least as far as I understood – the process of pushing changes from git to SVN is more or less automated (correct me if I'm wrong here, Nikita/Peter). Now the next steps are to move the toolage from SVN to git. That means: * Switch Source Retrieval for Docs building on docs.php.net from svn.php.net to git.php.net * Switch Generation of revcheck-files from svn to git (Work is already done at https://github.com/phpdoctest/doc-base/blob/master/scripts/revcheck.php) * Verify that everything works as expected When that is finished and accepted we can move over to the next stage: * Switch Source Retrieval for Docs building on rsynv.php.net from SVN to git * Setup Mirroring and processes to merge PRs from GitHub to documentation git. * Rewrite setup-instructions and send email to docs team regarding new process And then we can finally make SVN readonly. (and the cronjobs on svngit.php.net need top be shut down) I've also added the ToDo list to https://github.com/phpdoctest/meta/wiki/todo, so that everyone can follow the process. As the next steps need access to euk2.php.net which I currently do not have, I'd need someone to actually do those next tasks. Access – according to the wiki – have bjori, mgdm, mj, nilgun, philip, salathe, sobak, tyrael and yannick. I'd be very happy if one of you could ping me so that we can check the next steps. Thank you all for the support during the last weeks. Cheers Andreas Am 04.02.20 um 08:09 schrieb Andreas Heigl: > Hey folks. > > During the last year I took a bit of time aside to bring the > documentation from SVN to git. And about a month ago I informed the > DOCs-Mailinglist about the current status and the fact that we are ready > to move to the next step[1]. Now some tasks need to be done by people > with appropriate karma to be able to get on with the whole thing, but > all the background tasks are done and awaiting further processing. > > Sadly there was no response so far. Neither on the email as such nor on > the different tasks. > > So the main question is now, how the PHP-Project wants to go on with > moving the documentation from SVN to git? Is there any interest in > continuing this project? And if so, who can either take on the necessary > steps or provide us with the appropriate credentials and access rights > that we can do them ourselves? > > Thanks for reading and looking forward to the results. > > Cheers > > Andreas > > [https://news-web.php.net/php.doc/969387429] > -- ,,, (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 | +---------------------------------------------------------------------+