Everything

php

Moving from SVN to git - finally!

php.internals

Andreas Heigl

5 years ago

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

For the team: Andreas

--
,,,
(o o)
+---------------------------------------------------------ooO-(_)-Ooo-+
| Andreas Heigl                                                       |
| mailto:andreas@heigl.org                  N 50°22'59.5" E 08°23'58" |
| https://andreas.heigl.org                                           |
+---------------------------------------------------------------------+
| https://hei.gl/appointmentwithandreas                               |
+---------------------------------------------------------------------+

yannick

5 years ago

Hi all,

As I can understand, tomorrow, edit.php.net will be stopped... and
revcheck.php was not ready.
So, how translators can see witch files is outdated ?

Best,
Yannick


Le mar. 29 déc. 2020 à 19:34, Andreas Heigl <andreas@heigl.org> a écrit :

Good Guy

5 years ago

On 29/12/2020 18:34, Andreas Heigl wrote:

>
> 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
>

Why kill it so soon?  Keep it for two or three more weeks in tandem
with  GIT for the process to settle down.    Sometimes moving can go
wrong so there is always a fall back.

--
With over 1.2 billion devices now running Windows 10, customer
satisfaction is higher than any previous version of windows.

Tiffany Taylor

5 years ago

On Tue, Dec 29, 2020, 1:11 PM 😉 Good Guy 😉 <xfsgpr@hotmail.com> wrote:

> On 29/12/2020 18:34, Andreas Heigl wrote:
> >
> > 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
> >
>
> Why kill it so soon?  Keep it for two or three more weeks in tandem
> with  GIT for the process to settle down.    Sometimes moving can go
> wrong so there is always a fall back.
>

>

They have been running in tandem for several months already. Someone
involved with the migration, please correct me if I'm wrong. Members of the
docs team who also contribute through GitHub have spent the past several
months this year maintaining a repo for SVN and a repo for GitHub, it has
been frustrating to keep them correctly synced.

Girgias

5 years ago

Just for information I'm working on establishing a revcheck from git,
I'm expecting this to be done within the next couple of days as last year I
was playing around making doc.php.net a static website built via GitLab CI.

This would also take care of mapping SVN revision to git commits, such a
hashmap can be easily create after parsing the content of the following git
command:
git log --grep="git-svn-id"
--format="%H:%(trailers:valueonly,unfold,key=git-svn-id,separator=%n)"
used in the doc-en repo.

I will try to keep the list updated on the progress.

Best regards,

George P. Banyard

Good Guy

5 years ago

On 29/12/2020 20:01, Tiffany Taylor wrote:

> On Tue, Dec 29, 2020, 1:11 PM 😉 Good Guy 😉 <xfsgpr@hotmail.com
> <mailto:xfsgpr@hotmail.com>> wrote:
>
>     On 29/12/2020 18:34, Andreas Heigl wrote:
>     >
>     > 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 <http://git.php.net>
>     >
>
>     Why kill it so soon?  Keep it for two or three more weeks in tandem
>     with  GIT for the process to settle down.    Sometimes moving can go
>     wrong so there is always a fall back.
>
>
>
> They have been running in tandem for several months already. Someone
> involved with the migration, please correct me if I'm wrong. Members
> of the docs team who also contribute through GitHub have spent the
> past several months this year maintaining a repo for SVN and a repo
> for GitHub, it has been frustrating to keep them correctly synced.
>

I just went to the base and didn't get anything so I concluded that it
hasn't been migrated yet.

<https://git.php.net/repository/doc/base.git>

--
With over 1.2 billion devices now running Windows 10, customer
satisfaction is higher than any previous version of windows.

Tiffany Taylor

5 years ago

On Tue, Dec 29, 2020 at 4:44 PM 😉 Good Guy 😉 <xfsgpr@hotmail.com> wrote:

> On 29/12/2020 20:01, Tiffany Taylor wrote:
> > On Tue, Dec 29, 2020, 1:11 PM 😉 Good Guy 😉 <xfsgpr@hotmail.com
> > <mailto:xfsgpr@hotmail.com>> wrote:
> >
> >     On 29/12/2020 18:34, Andreas Heigl wrote:
> >     >
> >     > 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 <http://git.php.net>
> >     >
> >
> >     Why kill it so soon?  Keep it for two or three more weeks in tandem
> >     with  GIT for the process to settle down.    Sometimes moving can go
> >     wrong so there is always a fall back.
> >
> >
> >
> > They have been running in tandem for several months already. Someone
> > involved with the migration, please correct me if I'm wrong. Members
> > of the docs team who also contribute through GitHub have spent the
> > past several months this year maintaining a repo for SVN and a repo
> > for GitHub, it has been frustrating to keep them correctly synced.
> >
>
> I just went to the base and didn't get anything so I concluded that it
> hasn't been migrated yet.
>
> <https://git.php.net/repository/doc/base.git>
>

`git clone https://git.php.net/repository/doc/base.git` works.

Girgias

5 years ago

On Wed, 30 Dec 2020 at 01:06, Tiffany Taylor <tiffany.k.taylor@gmail.com>
wrote:

> On Tue, Dec 29, 2020 at 4:44 PM 😉 Good Guy 😉 <xfsgpr@hotmail.com> wrote:
>
> > On 29/12/2020 20:01, Tiffany Taylor wrote:
> > > On Tue, Dec 29, 2020, 1:11 PM 😉 Good Guy 😉 <xfsgpr@hotmail.com
> > > <mailto:xfsgpr@hotmail.com>> wrote:
> > >
> > >     On 29/12/2020 18:34, Andreas Heigl wrote:
> > >     >
> > >     > 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 <http://git.php.net>
> > >     >
> > >
> > >     Why kill it so soon?  Keep it for two or three more weeks in tandem
> > >     with  GIT for the process to settle down.    Sometimes moving can
> go
> > >     wrong so there is always a fall back.
> > >
> > >
> > >
> > > They have been running in tandem for several months already. Someone
> > > involved with the migration, please correct me if I'm wrong. Members
> > > of the docs team who also contribute through GitHub have spent the
> > > past several months this year maintaining a repo for SVN and a repo
> > > for GitHub, it has been frustrating to keep them correctly synced.
> > >
> >
> > I just went to the base and didn't get anything so I concluded that it
> > hasn't been migrated yet.
> >
> > <https://git.php.net/repository/doc/base.git>
> >
>
> `git clone https://git.php.net/repository/doc/base.git`
> <https://git.php.net/repository/doc/base.git> works.
>

Note the summary is located here:
https://git.php.net/?p=doc/base.git;a=summary

Best regards,

George P. Banyard

Nikita Popov

5 years ago

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