Newsgroups: php.doc,php.internals
Path: news.php.net
Xref: news.php.net php.doc:969387756 php.internals:112661
MIME-Version: 1.0
References: <b07ee32e-f002-b832-6577-1a9e1c9e63db@heigl.org>
In-Reply-To: <b07ee32e-f002-b832-6577-1a9e1c9e63db@heigl.org>
Date: Wed, 30 Dec 2020 14:58:29 +0100
Message-ID: <CAF+90c8xQzvTiDnOov=Ak+dPy=eEnZ775=iUaxiy=YzS=FJM_Q@mail.gmail.com>
To: Andreas Heigl <andreas@heigl.org>
Cc: PHP Documentation ML <phpdoc@lists.php.net>, PHP internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="000000000000db67cb05b7aee768"
Subject: Re: Moving from SVN to git - finally!
From: nikita.ppv@gmail.com (Nikita Popov)

--000000000000db67cb05b7aee768
Content-Type: text/plain; charset="UTF-8"

On Tue, Dec 29, 2020 at 7:34 PM Andreas Heigl <andreas@heigl.org> wrote:

> Hey folks!
>
> After some years we are finally at the point to do what so many have
> been asking for: We will move the source-control of the
> PHP-Documentation from SVN to git!
>
> Tomorrow!
>
> TL;DR
>
> Tomorrow we will remove docs-karma from SVN, do a final transition and
> then add doc-karma to git. Then all contributions to the
> PHP-Documentation will be via git.php.net
>
> Slightly longer version:
>
> Throughout the last year we continuously moved the commits from SVN over
> to the different repositories at git.php.net. 2 Days ago we finally
> switched the actually creation of the docs from using the SVN-sources to
> using the git-sources. It was a seamless transition and the broken
> translations were broken before. So we managed to switch the VCS without
> anyone noticing ;-)
>
> But that will not be possible for the next step.
>
> As everyone that is currently contributing to the docs via SVN will need
> to do at least 2 things to be able to continue contributing!
>
> * Checkout the docs-base from https://git.php.net/repository/doc/base.git
> * Check out the english documentation from git@git.php.net:/doc/en.git
> And if you are doing translations:
> * Check out your respective language from
> git@git.php.net:/doc/[language].git
>
> Yes! You've seen that right! We moved away from the monorepo to one repo
> per language. As at this point in time there are access restrictions on
> the different languages this was a necessary move. There are pros and
> cons to that that were addressed when we started that voyage. And you
> can feel free to discuss them as soon as the transition has been made
> and you have found someone doing the necessary work for a further change
> ;-)
>
> And as git doesn't know about "revisions" we had to change one thing for
> the translations: So far you kept the revision of the english doc you
> base the translation on in the attribute "en-revision". That will now
> change! After the switch you will need to add the _commit-hash_ of the
> english doc there instead!
>
> Apart from that the translation workflow itself stays the same. We only
> changed the Version Control System, nothing else.
>
> So what will be the next steps now?
>
> As already mentioned: Sometime tomorrow we will switch off karma for
> svn.php.net.
> Then we will do one last transition to git and modify the repos so that
> the revision is replaced by the commit-hash
> Then we will switch karma on for git.php.net
> And when that is finished, we will create the github mirrors so that
> everyone can create PRs for the docs and the translations!
>
> That's it.
>
> Almost...
>
> As there is one thing though that is not done yet which we need some
> help with: The revision-check! For those of you that do not know what it
> is: Head over to http://doc.php.net/revcheck.php and have a look. In
> short: It shows how outdated a translation is. This was tightly coupled
> to SVN and it is much harder to convert to git as originally
> anticipated. So any help on that is highly appreciated! Patches for
> http://git.php.net/?p=web/doc.git;a=blob;f=scripts/rev.php are
> definitely welcome!
>
> But that is something for a new challenge!
>
> Looking forward to being able to put a decade long challenge for the
> community and a 4+ year challenge for me to a good end tomorrow!
>
> Let's all cross fingers that everything goes as smooth as expected!
>
> Cheers
>

The SVN -> Git migration has finished. If you have phpdoc karma, you should
be able to push to the "doc" repos listed on http://git.php.net/ now.

Note that the upstream Git repos are hosted on git.php.net (e.g.
http://git.php.net/?p=doc/en.git;a=summary), but have mirrors on GitHub (
https://github.com/php/doc-en). You should always push changes to the
upstream repo, not the GitHub mirror. The GitHub mirrors only exist to
accept pull requests.

It will take a while for all the tooling to catch up, so in the meantime
some notes on how we typically merge pull requests in php-src:

1. Append ".patch" to the pull request URL:
https://github.com/php/doc-en/pull/293.patch
2. Download the patch: wget
https://patch-diff.githubusercontent.com/raw/php/doc-en/pull/293.patch
3. Apply the patch: git am 293.patch
4. Auto-close the pull request: git commit --am and add "Closes
php/doc-en#293" to the commit message
5. Push: git push origin master

I expect this workflow to be automated for documentation repositories in
the future.

Regards,
Nikita

--000000000000db67cb05b7aee768--