From owner-freebsd-stable@FreeBSD.ORG Wed Jun 12 21:48:23 2013 Return-Path: Delivered-To: freebsd-stable@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id F3AF6C89 for ; Wed, 12 Jun 2013 21:48:22 +0000 (UTC) (envelope-from nonesuch@longcount.org) Received: from mail-qc0-x22e.google.com (mail-qc0-x22e.google.com [IPv6:2607:f8b0:400d:c01::22e]) by mx1.freebsd.org (Postfix) with ESMTP id B7F901653 for ; Wed, 12 Jun 2013 21:48:22 +0000 (UTC) Received: by mail-qc0-f174.google.com with SMTP id m15so4158740qcq.5 for ; Wed, 12 Jun 2013 14:48:22 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=subject:references:from:content-type:x-mailer:in-reply-to :message-id:date:to:content-transfer-encoding:mime-version :x-gm-message-state; bh=gDeHQIa91x2T88FL6n65UkbFkfOUfTeS2r9xijKDmz8=; b=Z0fmcpJNvMnNW9j8llUcHN5vL8jij6Hkh4UQ5XeBkGOp0VdRMDjuXMrxridMXAOIuQ Dzrf7Cp0pkdUrC6IjKomnpupJwDb1j7mFRIlyO278hRwy9ni4jl7LQA21eUvcxanNZeM 2p540ZcEYkqHlaXbWrq9ClqBKBs7Ed3UjWqAWlh8lpeYgtEXrsao4ck4375he0o6p6Kw eBnAq1lOPXw8b8vMjJXNtaKbTqG7pX7CkSPc14gHg/vXWMtgrVtYT8DT3GFscwGUlZG3 AXq7YLC+gztfsaMKC0VMpoTnRecSaJobYDbFqxzNPkFspw0VzFfoLXhvDEPgj9RxLdKS fLTA== X-Received: by 10.224.25.195 with SMTP id a3mr54440qac.9.1371073702134; Wed, 12 Jun 2013 14:48:22 -0700 (PDT) Received: from [97.33.136.210] (210.sub-97-33-136.myvzw.com. [97.33.136.210]) by mx.google.com with ESMTPSA id d5sm22888610qel.4.2013.06.12.14.48.20 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 12 Jun 2013 14:48:21 -0700 (PDT) Subject: Re: request for your comments on release documentation References: <20130612213115.GA61462@anubis.morrow.me.uk> From: Mark Saad Content-Type: text/plain; charset=us-ascii X-Mailer: iPhone Mail (10B329) In-Reply-To: <20130612213115.GA61462@anubis.morrow.me.uk> Message-Id: <69B15075-3CAC-47D4-BCB4-17657A29BA14@longcount.org> Date: Wed, 12 Jun 2013 17:48:17 -0400 To: "freebsd-stable@FreeBSD.org" Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (1.0) X-Gm-Message-State: ALoCoQlEh7lAOcmI30lGeeKRfsX6tFDEIoDWbYounYZV703kZBFUG4APh2T0CxFiVI/qpIgZBEJW X-BeenThere: freebsd-stable@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Production branch of FreeBSD source code List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Jun 2013 21:48:23 -0000 On Jun 12, 2013, at 5:31 PM, Ben Morrow wrote: > Quoth hrs@FreeBSD.org: >>=20 >> I would like your comments on release notes for each release. >> Although I have been working on editing them for years, the workflow >> is still not optimal and sometimes delay of the preparation became an >> obstacle for release process. I would like to improve it, but before >> that I would like to know what are desired of the contents which >> people think. >>=20 >> Release Notes is just listing the changes between the two releases. >> It includes user-visible change (bugfix and/or UI change), new >> functionality, and performance improvement. Minor changes such as >> one in kernel internal structure are omitted. I always try to keep >> these series of relnotes items are correct and reasonably >> comprehensive, but this lengthy list may be boring and >> technically-correct descriptions can be cryptic for average users. >=20 > I find the lengthy list extremely valuable. It takes a little time to go > through it carefully, but being able to be reasonably sure nothing > important is missing makes upgrades easier, not harder. >=20 >> So, my questions are: >>=20 >> 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, >=20 > Seems pretty good to me. The only thing I might change is the order: > generally speaking, I'm most interested in the 'User-visible > incompatibilites' section, then in the userland and contrib changes, and > then the kernel changes. The security advisories section is least > useful, because it generally just lists advisories I've already seen and > know have been already fixed; it's a good thing it's there, if only to > make it clear the project takes security seriously, but I might move it > to the end. >=20 >> 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%". >=20 > It's interesting, but IMHO only worth it if it's easy. It's not worth > holding a release up for. >=20 >> 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. >=20 > The only important additional thing that might be useful would be links > to relevant mailing-list threads in addition to the SVN links. I can see > that might be quite a bit of work to compile, though, so it may not be > possible. >=20 >> Although the other release documentations---Errata, Installation >> Notes, ReadMe, and Hardware Notes---also need some improvements, >> please focus on Release Notes only. And you might think quality of >> English writing are not good, please leave that alone for now. >=20 > There's nothing wrong with your English. >=20 > Ben >=20 > ______________________________ Two points. I like the details of the release notes . More detail here is al= ways welcomed. As a professional FreeBSD SA it helps to have detailed notes.= Second, goes to item 3 noted above: a summary of pr' filed on the previous r= elease and their current state would be a huge help as well. Say in the cas= e of 9.0 to 9.1 it would help if I could read pr's filed about 9.0 that were= fixed / addressed, etc in 9.1 . =20 --- Mark saad | mark.saad@longcount.org