Moving PHP documentation to Git repository

11 years ago by crosse@2bepublished@Christoph Rosse — view source

unread

Hi internals.

What do you think about moving the PHP documentation to a Git repository, mirrored on Github? Doing this would make it possible for everybody to extend the documentation easily by creating pull requests.

Today one has to get an SVN account to edit the docu or you have to use https://edit.php.net/ which does not work as expected (at least for me when I tried to update some German documentation). My changes have not been integrated for some months (I had to write an email to somebody of the doc team to apply the changes).

Symfony does it this way (see https://github.com/symfony/symfony-docs/) and I like it very much. It is really easy to extend/update parts of the docu which are not complete or outdated and I am sure that it is comfortable and timesaving for the doc team, too.

What do you think?

Best regards
Christian

As one who's had very similar experiences when trying to update some
documentation via. edit.php.net (no feedback, no integration etc.) I
would really love to see this feature.

best regards

christoph

--
Christoph Rosse
Softwaredevelopment | Operations

2bePUBLISHED Internet Services Austria GmbH
Brünner Straße 85/2, 1210 Wien
Tel.: 0043.1.9971500
Fax.: 0043.1.997150066
E-mail: crosse@2bepublished.at
Skype: christoph.rosse
Home: http://www.2bepublished.at

11 years ago by Pierre Joye — view source

unread

Hi internals.

What do you think about moving the PHP documentation to a Git repository,
mirrored on Github? Doing this would make it possible for everybody to
extend the documentation easily by creating pull requests.

Today one has to get an SVN account to edit the docu or you have to use
https://edit.php.net/ which does not work as expected (at least for me when
I tried to update some German documentation). My changes have not been
integrated for some months (I had to write an email to somebody of the doc
team to apply the changes).

Symfony does it this way (see https://github.com/symfony/symfony-docs/)
and I like it very much. It is really easy to extend/update parts of the
docu which are not complete or outdated and I am sure that it is comfortable
and timesaving for the doc team, too.

What do you think?

Best regards
Christian

As one who's had very similar experiences when trying to update some
documentation via. edit.php.net (no feedback, no integration etc.) I would
really love to see this feature.

Really? That's not too good as we have been promoted this tool for
some time already.

However adding the php-doc list to CC so they can answer and give us
some feedback/info.

Cheers,

Pierre

@pierrejoye | http://www.libgd.org

11 years ago by Pierre Joye — view source

unread

and now with the right name...

Hi internals.

What do you think about moving the PHP documentation to a Git repository,
mirrored on Github? Doing this would make it possible for everybody to
extend the documentation easily by creating pull requests.

Today one has to get an SVN account to edit the docu or you have to use
https://edit.php.net/ which does not work as expected (at least for me when
I tried to update some German documentation). My changes have not been
integrated for some months (I had to write an email to somebody of the doc
team to apply the changes).

Symfony does it this way (see https://github.com/symfony/symfony-docs/)
and I like it very much. It is really easy to extend/update parts of the
docu which are not complete or outdated and I am sure that it is comfortable
and timesaving for the doc team, too.

What do you think?

Best regards
Christian

As one who's had very similar experiences when trying to update some
documentation via. edit.php.net (no feedback, no integration etc.) I would
really love to see this feature.

Really? That's not too good as we have been promoted this tool for
some time already.

However adding the php-doc list to CC so they can answer and give us
some feedback/info.

Cheers,

Pierre

@pierrejoye | http://www.libgd.org

--
Pierre

@pierrejoye | http://blog.thepimp.net | http://www.libgd.org

11 years ago by Ferenc Kovacs — view source

unread

On Tue, Jun 25, 2013 at 9:45 AM, Christoph Rosse crosse@2bepublished.at
wrote:

Hi internals.

What do you think about moving the PHP documentation to a Git
repository,
mirrored on Github? Doing this would make it possible for everybody to
extend the documentation easily by creating pull requests.

Today one has to get an SVN account to edit the docu or you have to use
https://edit.php.net/ which does not work as expected (at least for
me when
I tried to update some German documentation). My changes have not been
integrated for some months (I had to write an email to somebody of the
doc
team to apply the changes).

Symfony does it this way (see https://github.com/symfony/symfony-docs/
)
and I like it very much. It is really easy to extend/update parts of
the
docu which are not complete or outdated and I am sure that it is
comfortable
and timesaving for the doc team, too.

What do you think?

Best regards
Christian

As one who's had very similar experiences when trying to update some
documentation via. edit.php.net (no feedback, no integration etc.) I
would
really love to see this feature.

Really? That's not too good as we have been promoted this tool for
some time already.

However adding the php-doc list to CC so they can answer and give us
some feedback/info.

Cheers,

Pierre

@pierrejoye | http://www.libgd.org

there were some initial discussion and work done on moving the docs to git,
see
https://wiki.php.net/doc/git
http://git.php.net/?p=web/doc-editor.git;a=shortlog;h=refs/heads/GIT_READY
http://marc.info/?l=phpdoc&m=132321958514090&w=2

but it seems that we lost momentum, but I think that this isn't a technical
problem, just lack of interest (svn and the online editor just works for
the regulars), maybe others have different opinions on this.
and I'm fairly certain that the slow integration of the patches also not a
technical problem as well.
I think that it would worth more to figure out and fix the underlying
problem which causes the current delay for integrating the incoming patches.
moving to git/github without fixining the underlying issue would only mean
that we switched to pull requests not getting accepted in a timely
manner(which is unfortunately common with our other git/github repos).

--
Ferenc Kovács
@Tyr43l - http://tyrael.hu

11 years ago by David Soria Parra — view source

unread

there were some initial discussion and work done on moving the docs to git,
see
https://wiki.php.net/doc/git
http://git.php.net/?p=3Dweb/doc-editor.git;a=3Dshortlog;h=3Drefs/heads/GIT_=
READY
http://marc.info/?l=3Dphpdoc&m=3D132321958514090&w=3D2

but it seems that we lost momentum, but I think that this isn't a technical
problem, just lack of interest (svn and the online editor just works for
the regulars), maybe others have different opinions on this.
and I'm fairly certain that the slow integration of the patches also not a
technical problem as well.
I think that it would worth more to figure out and fix the underlying
problem which causes the current delay for integrating the incoming patches=
.
moving to git/github without fixining the underlying issue would only mean
that we switched to pull requests not getting accepted in a timely
manner(which is unfortunately common with our other git/github repos).

generally speaking i am in favor in moving more and more to git. we lost momentum
and I am stuck with a new job and RMing. I can help with technical questions
but don't hav emuch time implementing it.

11 years ago by Klaus Silveira — view source

unread

there were some initial discussion and work done on moving the docs to
git,
see
https://wiki.php.net/doc/git

http://git.php.net/?p=3Dweb/doc-editor.git;a=3Dshortlog;h=3Drefs/heads/GIT_=

READY
http://marc.info/?l=3Dphpdoc&m=3D132321958514090&w=3D2

but it seems that we lost momentum, but I think that this isn't a
technical
problem, just lack of interest (svn and the online editor just works for
the regulars), maybe others have different opinions on this.
and I'm fairly certain that the slow integration of the patches also not
a
technical problem as well.
I think that it would worth more to figure out and fix the underlying
problem which causes the current delay for integrating the incoming
patches=
.
moving to git/github without fixining the underlying issue would only
mean
that we switched to pull requests not getting accepted in a timely
manner(which is unfortunately common with our other git/github repos).

generally speaking i am in favor in moving more and more to git. we lost
momentum
and I am stuck with a new job and RMing. I can help with technical
questions
but don't hav emuch time implementing it.

I'm also in favor of moving to Git. The amount of contributions to the
brazilian portuguese translation would be much more significant if we had a
streamlined contribution system, which pull requests on Github allow quite
easily. What are the current problems of Git migration?

11 years ago by Hannes Magnusson — view source

unread

On Tue, Jun 25, 2013 at 12:45 AM, Christoph Rosse
crosse@2bepublished.at wrote:

Hi internals.

What do you think about moving the PHP documentation to a Git repository,
mirrored on Github? Doing this would make it possible for everybody to
extend the documentation easily by creating pull requests.

Today one has to get an SVN account to edit the docu or you have to use
https://edit.php.net/ which does not work as expected (at least for me when
I tried to update some German documentation). My changes have not been
integrated for some months (I had to write an email to somebody of the doc
team to apply the changes).

Symfony does it this way (see https://github.com/symfony/symfony-docs/)
and I like it very much. It is really easy to extend/update parts of the
docu which are not complete or outdated and I am sure that it is comfortable
and timesaving for the doc team, too.

What do you think?

Best regards
Christian

As one who's had very similar experiences when trying to update some
documentation via. edit.php.net (no feedback, no integration etc.) I would
really love to see this feature.

Could you guys fill out http://www.php.net/git-php.php please? - It is
also important to use the correct mailinglist :)

As for the move to Git, if someone is willing to do the work then by
all means go for it - but I don't understand how that is some magic
fix?
You are complaining about patches being available but not applied, how
would github fix that?
Doesn't that just add yet another platform that we don't have manpower
to manage?

Also, our current tooling will need a lot of work, but the online
editor and our revision control for translations to name two big jobs.

The docs and websites don't operate in the same way as internals@
does. We employ a lot of trust in these neck of the woods, people with
karma to do stuff can actually do what they think is best without
going through daunting process, so once you've been around for a
little while and get a neat idea you want to work on, you don't have
to ask anyone or get permission - just do it!
If you want to work on git support for our tools, go for it.

There isn't any point in discussing things and coming to decisions
when there is noone that is able or willing to do the work. If there
work is there however.. :D

-Hannes

11 years ago by Terry Ellison — view source

unread

What do you think about moving the PHP documentation to a Git repository, mirrored on Github? Doing this would make it possible for everybody to extend the documentation easily by creating pull requests.

Today one has to get an SVN account to edit the docu or you have to use https://edit.php.net/ which does not work as expected (at least for me when I tried to update some German documentation). My changes have not been integrated for some months (I had to write an email to somebody of the doc team to apply the changes).

Symfony does it this way (see https://github.com/symfony/symfony-docs/) and I like it very much. It is really easy to extend/update parts of the docu which are not complete or outdated and I am sure that it is comfortable and timesaving for the doc team, too.

+1

Regards Terry Ellison

11 years ago by johannes@schlueters.de — view source

unread

Hi internals.

What do you think about moving the PHP documentation to a Git
repository, mirrored on Github? Doing this would make it possible for
everybody to extend the documentation easily by creating pull
requests.

Basically that is good. To the best of my knowledge the issue though, is
not will but time. Migrating the docs is not just converting the repo,
like with PECL repos but changing the supporting infrastructure. For
instance there are tools which help to identify outdated translations
and the mentioned editor which all have to be adopted. If you want to
help there the docs group certainly would welcome it.

That aside: resources is also the issue with the online editor. We have
too few people working on docs, so in the end it doesn't make much
difference if they don't have time to review edit.php.net or github.
(while reviewing on edit.php.net has the benefit that it can directly
validate the docbook, github can't)

johannes
(who is one of the bad people not really actively helping with docs)

11 years ago by Sherif Ramadan — view source

unread

On Tue, Jun 25, 2013 at 5:10 AM, Johannes Schlüter
johannes@schlueters.dewrote:

Hi internals.

What do you think about moving the PHP documentation to a Git
repository, mirrored on Github? Doing this would make it possible for
everybody to extend the documentation easily by creating pull
requests.

Basically that is good. To the best of my knowledge the issue though, is
not will but time. Migrating the docs is not just converting the repo,
like with PECL repos but changing the supporting infrastructure. For
instance there are tools which help to identify outdated translations
and the mentioned editor which all have to be adopted. If you want to
help there the docs group certainly would welcome it.

That aside: resources is also the issue with the online editor. We have
too few people working on docs, so in the end it doesn't make much
difference if they don't have time to review edit.php.net or github.
(while reviewing on edit.php.net has the benefit that it can directly
validate the docbook, github can't)

I'm all for docs moving to git, but I have to say it would be a purely
cosmetic move. This won't change the pace at which our patches are getting
through or the fact that the lack of man-power can be overwhelming for
docs. The documentation is over 10,000 pages and growing with multiple
translations. PHP also suffers from a problem where patches go into php-src
that never get into the changelog for some reason and end up becoming
documentation bugs. I've definitely fixed a number of those in
bugs.php.netand I know I'm not the only one that has complained about
this problem.
It's hard to keep up with the pace at which PHP changes and consistently
document that.

I will say that we do need more people helping out with docs before we
should consider investing the resources in moving docs to git. Again, this
move would only serve to be superficial in the long-run.

johannes
(who is one of the bad people not really actively helping with docs)

So YOU'RE the one! (kidding it's been a while since I've made some
commits myself)

11 years ago by Christian Stoller — view source

unread

That aside: resources is also the issue with the online editor. We have
too few people working on docs, so in the end it doesn't make much
difference if they don't have time to review edit.php.net or github.
(while reviewing on edit.php.net has the benefit that it can directly
validate the docbook, github can't)

The difference is that the Git repo with its translations could be viewed very easily via Github. And it is possible to comment on pull requests or discuss them.
Plus: Others can see what pull requests have been created already and you can see at a first glance how many open pull requests there are.

When I used the online editor, I changed something but I didn't know if it has been saved correctly (especially when the changes have not been deployed after weeks) or if there is somebody who has ever seen my changes. In Github you see what you have changed. That motivates to work on ;-)

Christian

11 years ago by yannick.torres@gmail.com — view source

unread

Hi,

Just my two cent.
The online editor is actually a greats tool to edit & commit some changes
into the documentation for all translations. Please, don't view only the
EN part of the documentation.
If we plan to move to GitHub, there were a lot of work to do into the
editor to continue to use it. And I'm really not sur that I have the time
to do it.

I know there is actually a bug witch cause that the change aren't deployed
as they should be. I try to find some time to work on it, and I'm sur that
i can provide a fix in some few weeks. Just be patient with this, sorry.

So, as it was sayed, the delay between reviewed a patch with the editor or
the delay to review un pull request with GitHub is the same : if there are
no people to do the first, it's the same for the second ;)

Grest,
Yannick

2013/6/25 Christian Stoller stoller@leonex.de

That aside: resources is also the issue with the online editor. We have
too few people working on docs, so in the end it doesn't make much
difference if they don't have time to review edit.php.net or github.
(while reviewing on edit.php.net has the benefit that it can directly
validate the docbook, github can't)

The difference is that the Git repo with its translations could be viewed
very easily via Github. And it is possible to comment on pull requests or
discuss them.
Plus: Others can see what pull requests have been created already and you
can see at a first glance how many open pull requests there are.

When I used the online editor, I changed something but I didn't know if it
has been saved correctly (especially when the changes have not been
deployed after weeks) or if there is somebody who has ever seen my changes.
In Github you see what you have changed. That motivates to work on ;-)

Christian