Newsgroups: php.internals,php.doc
Path: news.php.net
Xref: news.php.net php.internals:55836 php.doc:969383263
Return-Path: <hannes.magnusson@gmail.com>
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Delivered-To: mailing list internals@lists.php.net
Received: (qmail 495 invoked from network); 17 Oct 2011 10:25:57 -0000
Received: from unknown (HELO lists.php.net) (127.0.0.1)
  by localhost with SMTP; 17 Oct 2011 10:25:57 -0000
Authentication-Results: pb1.pair.com smtp.mail=hannes.magnusson@gmail.com; spf=pass; sender-id=pass
Authentication-Results: pb1.pair.com header.from=hannes.magnusson@gmail.com; sender-id=pass
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.161.170 as permitted sender)
X-PHP-List-Original-Sender: hannes.magnusson@gmail.com
X-Host-Fingerprint: 209.85.161.170 mail-gx0-f170.google.com  
Received: from [209.85.161.170] ([209.85.161.170:42174] helo=mail-gx0-f170.google.com)
	by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP
	id 46/21-27630-3B20C9E4 for <phpdoc@lists.php.net>; Mon, 17 Oct 2011 06:25:56 -0400
Received: by ggnk5 with SMTP id k5so949915ggn.29
        for <multiple recipients>; Mon, 17 Oct 2011 03:25:53 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :cc:content-type;
        bh=d2RmHpf2U0O32tUtjSyolg3tlYhU0DLmwy7th1yeOII=;
        b=DfphJNAaPgKRR9wXSUfqOFZ4Hy/4UeAFYvxo41amooHtovnk1SyfQUlx/Gsop1vmiI
         2x3E8QbIgEzACgTCMb3IYPzcBZmjwoQl35rpAlluEfaebzCtj0GeZkz0RIr1LC2YA6F8
         Ri3Qecu04W/X1cGMzZfglPuuUDGVl71IgevQo=
MIME-Version: 1.0
Received: by 10.236.173.165 with SMTP id v25mr25557136yhl.22.1318847152935;
 Mon, 17 Oct 2011 03:25:52 -0700 (PDT)
Received: by 10.147.34.3 with HTTP; Mon, 17 Oct 2011 03:25:52 -0700 (PDT)
In-Reply-To: <CADNQb0X7eSO560EEyQ=S3-sjRnVc7GxOZBw3wDmJUFdNVU6PCg@mail.gmail.com>
References: <4E5B24DD.10903@sugarcrm.com>
	<op.v0yn2z06idpuyk@damnation>
	<4E671355.5060908@sugarcrm.com>
	<CAH-PCH4JaCrbuQzL+c5M6vYjfNEJXAUktLxmc7w5pfuLqdYiSQ@mail.gmail.com>
	<CADNQb0WK5sGO0EWRtALz6sM-+eFiat48VpNaEiWu5LNcPGhQcw@mail.gmail.com>
	<4E9A3EAC.6040501@sugarcrm.com>
	<CAEZPtU6hiCcCkHSh9DG7g+UJ71QM5iDQoDXPHt5qtBxp5ju5LA@mail.gmail.com>
	<CADNQb0X7eSO560EEyQ=S3-sjRnVc7GxOZBw3wDmJUFdNVU6PCg@mail.gmail.com>
Date: Mon, 17 Oct 2011 12:25:52 +0200
Message-ID: <CADNQb0XQjADkNejgcv6_tQoTiS76c54br40b-VXCFzrbZp2WjQ@mail.gmail.com>
To: Pierre Joye <pierre.php@gmail.com>, PHP Documentation ML <phpdoc@lists.php.net>
Cc: Stas Malyshev <smalyshev@sugarcrm.com>, Ferenc Kovacs <tyra3l@gmail.com>, 
	Gustavo Lopes <glopes@nebm.ist.utl.pt>, 
	"internals@lists.php.net" <internals@lists.php.net>
Content-Type: text/plain; charset=UTF-8
Subject: Re: [PHP-DEV] 5.4 beta
From: hannes.magnusson@gmail.com (Hannes Magnusson)

On Mon, Oct 17, 2011 at 12:24, Hannes Magnusson
<hannes.magnusson@gmail.com> wrote:
> On Sun, Oct 16, 2011 at 12:40, Pierre Joye <pierre.php@gmail.com> wrote:
>> hi,
>>
>> On Sun, Oct 16, 2011 at 4:17 AM, Stas Malyshev <smalyshev@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