On Jun 5, 2012, at 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")
I like it, although think we are mixing up the proposed argument feature with the proposed changelog feature :) Ideally we could insert extension specific changelog entries within the autogenerated list. Like when the extension was deprecated, or moved to PECL, or some other major change. Regards, Philip
