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