Re: Extension changelogs

On 06/05/2012 10:31 AM, Hannes Magnusson wrote:

On Wed, Feb 1, 2012 at 10:45 AM, Hannes Magnusson <hannes.magnusson@gmail.com> wrote:

On Wed, Feb 1, 2012 at 11:26, jpauli<jpauli@php.net> wrote:

On Wed, Feb 1, 2012 at 11:14 AM, Ulf Wendel<ulf.wendel@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.jones@oracle.com http://twitter.com/#!/ghrd