On 06/05/2012 10:31 AM, Hannes Magnusson wrote:
On Wed, Feb 1, 2012 at 10:45 AM, Hannes Magnusson
<hannes.magnus...@gmail.com> wrote:
On Wed, Feb 1, 2012 at 11:26, jpauli<jpa...@php.net> wrote:
On Wed, Feb 1, 2012 at 11:14 AM, Ulf Wendel<ulf.wen...@phpdoc.de> wrote:
Am 01.02.2012 10:36, schrieb jpauli:
Well, we already have some changelog inside an extension documentation,
think like php.net/manual/en/curl.constants.php
<http://php.net/manual/en/curl.constants.php> for example.
I admit its not centralized.
Do you mean we shall add a special central changelog section summing up
the changes for every extension ?
Good morning Julien!
Hannes has cited a commit of mine in which I update a "Change History"
such as:
http://de.php.net/manual/en/mysqlnd-ms.changes.php
http://de.php.net/manual/en/mysqlnd-qc.changes.php
These two "Change Histories"...
... are for a two PECL extensions
... try to be comprehensive summaries of changes
... link to the main sections for details
... accomplished by CHANGES files in the source tree
... increase visibility and awareness
... may not list all minor CHANGES file entries
You are asking about, for example,
http://php.net/manual/en/curl.constants.php . This also exists in the above
named PECL extensions documentation for constants, configuration directives,
functions and so forth. This is what I refer to as "... link to main
sections for details" above. Naming changes in such constants, ... lists is
good, is proven, is useful... - please let's continue with it.
However, I felt that there was room for something in-between change
details scattered in the main sections, a not so much visible
CHANGES/NEWS/... file in the source tree and upgrade guidelines. I called
this something "Change History" (I'm open to rename it).
As I understand it, Hannes suggests to have a "Change History" or "Change
Log" for every extension as the necessary change summary information is
already in the central NEWS file. Similar to my PECL extension case.
I do like that proposal. Though, one should be aware of the additional
work. I would have had appreciated to find a template in the manual that I
could have copied for my PECL extension case.
Ulf
That makes things clearer to me :)
So, yes Hannes, I do like the idea :) but like Ulf said, we should compute
the additional work needed to get those new chapters inside each supported
extension. We support *lots* of PECL extensions inside the main php-doc tree
(http://www.php.net/manual/en/extensions.alphabetical.php) , so that would
represent a lot of work.
We already do some parts of the work in the form of changelogs on each
function page, introducing this new page could aggregate that and
provide more comprehensive information in the form of examples and
longer human readable text.
If we could do this for built-in exts first, and if it works out
expand it to the rest of the pecl extensions.
I think this will solve the docrot of the migration guides, as they
almost never get updated with new info after the .0 releases, which
gives the users the wrong impression of changes.
And needing to navigate through every single damn function in the
manual to see what has changed is very very annoying.
Soo... to start the process I patched PhD to aggregate all the exiting
changelog entries and spit them out in a new document.
It should be fairly easy to actually even spit out a complete
changelog page for every version of PHP automatically on
php.net/manual/changelog.php for example.
Attached is the PhD patch and trivial phpdoc patch.
Screenshots:
- http://prntscr.com/a5yml ("ext/strings")
- http://prntscr.com/a5yq2 (ext/mysql)
- http://prntscr.com/a5yrv ("ext/misc")
-Hannes
Hi Hannes,
Looks fine. Perhaps the repeating version numbers are a little
tedious and the sentence "Here is a list..." isn't needed, but neither
is a huge issue.
Chris
--
christopher.jo...@oracle.com
http://twitter.com/#!/ghrd
