Re: Extension changelogs

Ahoy Hannes! .oO( Yes, go, make the PHP manual better! ) Am 01.02.2012 11:45, schrieb Hannes Magnusson:

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.

Exactly: comprehensive overview, pit falls, eventually brief examples... For example, I have tried to explain the main motto/theme/idea for a version of my PECL extensions. Users may look at it, find that it is only a maintenance release and skip in order not to touch their running system. Or, users may jump on it because of a new super-duper feature they desire.

If we could do this for built-in exts first, and if it works out expand it to the rest of the pecl extensions.

.oO( Sure, but don't count on me, thus no "vote" from the lurker ;-) )

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.

Well, it cures the problem somewhat by: - creating central, comprehensive overviews - increasing pressure to update NEWS as it makes your work visible to all users A changelog is for sure better suited for finding migration hints than scanning every manual page. Though, it may still not be comparable to a migration guide. A migration guide may have an even coarser granularity. For example, the changelog of a PECL extension may describe how to get from 1.1 -> 1.2, 1.2 -> 1.3, ... 1.9 -> 2.0 but a migration guide may also describe the direct path from 1.0 -> 2.0. With core extensions, which are bound to PHP major releases, this may not be an issue. For PECL extensions, which are mostly free to choose their version numbers as I understand it, it may be. Whatever, if the PHP docs team can cope with the extra work, please go for the changelogs in the manual. I found to spend most time not for adding a changelog entry but for describing the change, incorporating it into the main sections and reasonable cross linking from the changelog to the main sections. Ulf