On Mon, Oct 17, 2011 at 12:24, Hannes Magnusson <hannes.magnus...@gmail.com> wrote: > On Sun, Oct 16, 2011 at 12:40, Pierre Joye <pierre....@gmail.com> wrote: >> hi, >> >> On Sun, Oct 16, 2011 at 4:17 AM, Stas Malyshev <smalys...@sugarcrm.com> >> wrote: >>> Hi! >>> >>> On 10/7/11 11:13 AM, Hannes Magnusson wrote: >>>> >>>> The UPGRADING file is also completely worthless. >>>> I have no idea what is going on, as a dev, nor as a documentor. >>>> Be it traits, closures, or whatever random new parameter or function was >>>> added. >>>> When 5.3 came around, I literally had to diff the sources to figure >>>> out what was going on, I am not going through that again. >>> >>> I've sent a separate email about undocumented stuff but I'm kind of confused >>> about UPGRADING file - what should be there and how it is related to NEWS? >>> Should one ad stuff both to NEWS and UPGRADING or I as RM should add stuff >>> from NEWS to UPGRADING later? Do we have process described anywhere? >> >> You (David and you) should ensure that the UPGRADING guide is kept >> updated. I would say that's not your role to do everything but to ask >> the respective developers to add notes in there. > > The UPGRADING file has usually served as a base for > php.net/migration53 for example. > Its been a quite confusing topic though, stuff added in bugfix > release.. should that go there too? > The migration docs generally list everything from BC issues to new > params constants and functions and classes within the .0 release, but > after that... not so much. > > We should probably try to come up with some RFC on this to try to keep > it consistent. > I also want to introduce a "changelog" for the docs, so users can > actually see what has changed and whats new. That would help users to > see new features, discover new things, and also make it easier for > them to see if they should re-read a certain page after a for example > doc security fix...
To clarify that a bit; "changelog" like NEWS in php-src. We would then have php.net/manual/en/changelog.php aggregating "news worthy changes to the docs". -Hannes -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
