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... -Hannes -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
