moving some READMEs to the wiki

11 years ago by Ferenc Kovacs — view source

unread

Hi,

I think some of the README files currently present in the php-src repo
would be better kept in the wiki and some of them are already
duplicated/made redundant by our existing wiki pages.

README.MAILINGLIST_RULES -> this should be in the wiki or on
php.netsomewhere, this doesn't belong to the code and is always the
same between
branches/versions.
README.WIN32-BUILD-SYSTEM -> this already points to the wiki as the
info in this file was outdated, so removing this file should be fine.
README.namespaces -> I think that namespaces are already well-known
and covered in the docs, so removing this should be fine.
README.input_filter -> this could be moved to the internals docs maybe.
README.UNIX-BUILD-SYSTEM -> I think this contains some info where
nowhere else is mentioned, but it was last changed in 2003 so somebody
should update if we want to keep it. Should be moved to the wiki imo.
README.TESTING2 -> it is somehow covered by
http://qa.php.net/phpt_details.php and I think that it would be better
having it in the wiki or on qa.php.net
README.TESTING -> also covered on the wiki and on qa,php,net but the
information is scattered around, so I think it would be a nice thing to
have central place where we can have everything in one place.
README.SUBMITTING_PATCH -> another thing that would be better having
on php.net or in the wiki (or both), it is slightly outdated (no mention
of git, still references http://pecl.php.net/bugs/, etc.).
README.STREAMS -> no update since 2003, it would be better in the
internal docs or in the wiki.
README.SELF-CONTAINED-EXTENSIONS -> no update since 2002, and already
covered in the internals docs:
http://php.net/manual/en/internals2.buildsys.configunix.php
README.PHP4-TO-PHP5-THIN-CHANGES -> should be safe to drop imo.
README.NEW-OUTPUT-API -> duplicated by
https://wiki.php.net/rfc/new-output-api but it would be nice having in
the internals docs also.
README.GIT-RULES -> this isn't php version specific and we have a
bunch of other git/git workflow docs in the wiki so I think it would be
better removing it from here.
README.EXT_SKEL -> I think we could keep this, but would be nice if
the docs at http://php.net/manual/en/internals2.buildsys.skeleton.phpcould
be synced.
README.EXTENSIONS -> no updates since 2001, only states php 4 specific
changes so I think it would be save to remove.

btw. if we could come up with a solution to have php version specific
documentation of the internals (we already do this for the userland api)
then we could move every other technical docs also from the repo too.
what do you think about this?

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

11 years ago by Sebastian Bergmann — view source

unread

Am 29.01.2013 12:21, schrieb Ferenc Kovacs:

what do you think about this?

--
Sebastian Bergmann Co-Founder and Principal Consultant
http://sebastian-bergmann.de/ http://thePHP.cc/

11 years ago by Derick Rethans — view source

unread

I think some of the README files currently present in the php-src repo
would be better kept in the wiki and some of them are already
duplicated/made redundant by our existing wiki pages.

Please leave them in the source tree. They describe how APIs work. A
wiki is an online medium only and it always takes me a ridiculous amount
of time to find anything there!

cheers,
Derick

--
http://derickrethans.nl | http://xdebug.org
Like Xdebug? Consider a donation: http://xdebug.org/donate.php
twitter: @derickr and @xdebug
Posted with an email client that doesn't mangle email: alpine

11 years ago by Stas Malyshev — view source

unread

Hi!

I think having stuff on the wiki is nice, but for things related to the
code - e.g., APIs, builds descriptions, etc. - they should stay in the
code. They are easier to find there and easier to keep up-to-date, and
also ensure they have the content relevant to specific version. We could
have a wiki mirror - if somebody volunteers to maintain the wiki
structure and keep it up-to-date. Do we have such person? I think first
we need to create a place - wiki or manual, but somewhere - where this
content is created and kept up-to-date, and properly versioned when
relevant. When it happens, we can start replacing some of the docs with
the links to this content.

Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227

11 years ago by Clint Priest — view source

unread

Hi!

I think having stuff on the wiki is nice, but for things related to the
code - e.g., APIs, builds descriptions, etc. - they should stay in the
code. They are easier to find there and easier to keep up-to-date, and
also ensure they have the content relevant to specific version. We could
have a wiki mirror - if somebody volunteers to maintain the wiki
structure and keep it up-to-date. Do we have such person? I think first
we need to create a place - wiki or manual, but somewhere - where this
content is created and kept up-to-date, and properly versioned when
relevant. When it happens, we can start replacing some of the docs with
the links to this content.
I agree that the repo should be the "source" from which the wiki pages
flow, but making them more readily accessible to people not even aware
of their existence (never downloaded a tarball) would really improve
visibility for non-core.

I know Ferenc already said there is something like it now, perhaps it
can be updated to bring these files into the wiki in an automated fashion?

If that's something that is needed/desired, I could head that up as a
step in the direction of building the number of core devs.

Alternatively as mentioned just a moment ago, the Wiki format is plainly
readable in text form so if we just switched to writing these repo files
in a more wiki-friendly format, they can simply be mirrored into the
wiki to make them more widely consumable without taking them out of the
repo.

-Clint

11 years ago by Ferenc Kovacs — view source

unread

Hi,

I think some of the README files currently present in the php-src repo
would be better kept in the wiki and some of them are already
duplicated/made redundant by our existing wiki pages.

Definitely a good idea, possibly a better one might be to have a link
to the github repo version? Then it's always the latest while still being
able to keep the files in the repo...

--
-Clint

We have something like that already: http://php.net/reST/
But I don't really like that because it introduces it's own meta markup so
the files are still readable plaintext but are having some basic formatting
when viewed on the web.
And not just that, but personally I think that it would be better if for
documentation purposes we could be using the documentation infrastructure
what we already have here and we also have a wiki where we could put the
process/management related stuff.
I fail to see why would somebody expect to find our release policy in the
release tarball or how would it help that you have a GIT readme when you
get the source already.
Another thing that comes to mind is that we would have a better ACL if we
could keep them in the docs/wiki as currently we can't hand out write
access to those files without also handing out write access for the whole
php-src repo Of Of course re-arranging the directory structure and creating
a new karma line for those files or managing the contributions through Pull
Requests could also work.
But I think that it is only a legacy stuff that we have those files in the
repo: we didn't had internals documentation or a wiki, so we just put
everything to the repository.

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

cc'ing the list.

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