On Wed, Feb 1, 2012 at 11: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. > Good and safe idea, I +1 > > 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. > With the new release process, it will makes things easier as we won't change any API on revisions nor minors. > > -Hannes > Julien
