Re: Extension changelogs

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