From owner-freebsd-current@FreeBSD.ORG Wed Jun 12 18:33:55 2013 Return-Path: Delivered-To: current@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id A06A0203; Wed, 12 Jun 2013 18:33:55 +0000 (UTC) (envelope-from feld@feld.me) Received: from out3-smtp.messagingengine.com (out3-smtp.messagingengine.com [66.111.4.27]) by mx1.freebsd.org (Postfix) with ESMTP id 5F8AB1992; Wed, 12 Jun 2013 18:33:55 +0000 (UTC) Received: from compute1.internal (compute1.nyi.mail.srv.osa [10.202.2.41]) by gateway1.nyi.mail.srv.osa (Postfix) with ESMTP id 15FA820E16; Wed, 12 Jun 2013 14:33:55 -0400 (EDT) Received: from frontend1.nyi.mail.srv.osa ([10.202.2.160]) by compute1.internal (MEProxy); Wed, 12 Jun 2013 14:33:55 -0400 DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d=feld.me; h= content-type:to:subject:references:date:mime-version :content-transfer-encoding:from:message-id:in-reply-to; s= mesmtp; bh=+/0Tqd64aKf6CAZ4aGhOC6Q9Ir4=; b=IJmWIlvh4Uo0riKEmMUnv ItrE839ICeh6a8cycVBMo16F9DDePvWRjeLSadQSeQ9KzWkafxc6CYTzkbIJIPFw B5Dt4gc/qjkaU0/lh6JhLSLFdu5CT3XuhULXYjGzv02Qha/iR9VZ+ayQqY6+v3bs HaPL3ypNxzlONREHEl6eB8= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d= messagingengine.com; h=content-type:to:subject:references:date :mime-version:content-transfer-encoding:from:message-id :in-reply-to; s=smtpout; bh=+/0Tqd64aKf6CAZ4aGhOC6Q9Ir4=; b=awLD z49acjVijv/QGVzMrTL+0TwR/Lkb2wtMkMucZFMzMHcwgJJHaJ517j+D5WE4diot Y09NIaJJCXStzaq9o2J/Vr1tJSZ0EHCu6CjUfrJiprVzBAJhAkb130HC+enDRvr9 5F1l9dMcUba4B0udelroslpNbp2ccJQ/dFPMcnc= X-Sasl-enc: YYIxrrVcMpdh9WAOi9jmpGByecSn72qZkQylbp+KXMHa 1371062034 Received: from markf.office.supranet.net (unknown [66.170.8.18]) by mail.messagingengine.com (Postfix) with ESMTPA id B7B29C00E81; Wed, 12 Jun 2013 14:33:54 -0400 (EDT) Content-Type: text/plain; charset=us-ascii; format=flowed; delsp=yes To: stable@freebsd.org, current@freebsd.org, "Hiroki Sato" Subject: Re: request for your comments on release documentation References: <20130613.024921.2080910235950489908.hrs@allbsd.org> Date: Wed, 12 Jun 2013 13:33:54 -0500 MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: "Mark Felder" Message-ID: In-Reply-To: <20130613.024921.2080910235950489908.hrs@allbsd.org> User-Agent: Opera Mail/12.15 (FreeBSD) X-BeenThere: freebsd-current@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Discussions about the use of FreeBSD-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Jun 2013 18:33:55 -0000 On Wed, 12 Jun 2013 12:49:21 -0500, Hiroki Sato wrote: > So, my questions are: > 1. What do you think about current granularity of the relnotes items? > Too detailed, good, or too rough? Currently, judgment of what is > included or not is based on user-visible, new functionality, or > performance improvement. Applicable changes are included as > relnotes items even if the changes are small, As a sysadmin I live and die by the granularity of release notes. If they weren't granular I'd end up having to read the commit logs and try to parse out changes myself. Sometimes changes aren't going to be obvious if you weren't aware of discussions on the -hackers, -current, or -stable lists. > 2. Do you want technical details? For example, just "disk access > performance was improved by 50%" or "Feature A has been added. > This changes the old behavior because ..., and as a result, it > improves disk access performance by 50%". I'm sure if you're too terse like in your first example people will jump to conclusions and be angry when disk performance isn't improved 50% in every possible situation, as well as the project receiving bad press for being too deceiving. If you want to be terse perhaps "Disk access improvements" is sufficient, and use the second example if you want to be more explicit. > 3. Is there missing information which should be in the relnotes? > Probably there are some missing items for each release, but this > question is one at some abstraction level. Link to commit log and > diff, detailed description of major incompatible changes, and so > on. I try to keep up with the development and changes in releases as best I can and I haven't noticed any glaring omissions over the last several releases. I think you're doing a fine job. Also, is there a reason this isn't a "living" document that can be updated as things get MFC'd to STABLE? It would help take load off your end and maybe speed up release once the freeze has happened and we begin the final grind through release candidates.