On Tue, Jun 5, 2012 at 7:03 PM, Christopher Jones
<christopher.jo...@oracle.com> wrote:
>
>
> 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.


The text was just random example :)
As for the repeating version numbers, you mean just skip the first
column (empty) when its the same as the previous one?

-Hannes

Reply via email to