From owner-freebsd-hackers@freebsd.org Thu Jun 27 00:45:20 2019 Return-Path: Delivered-To: freebsd-hackers@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 96CF715D63B4 for ; Thu, 27 Jun 2019 00:45:20 +0000 (UTC) (envelope-from markjdb@gmail.com) Received: from mail-io1-xd33.google.com (mail-io1-xd33.google.com [IPv6:2607:f8b0:4864:20::d33]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id A6FB48E5F4; Thu, 27 Jun 2019 00:45:19 +0000 (UTC) (envelope-from markjdb@gmail.com) Received: by mail-io1-xd33.google.com with SMTP id r185so898986iod.6; Wed, 26 Jun 2019 17:45:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=p0Utk0iWJmN7wGE4iUGfqdM0e+4KevxLcNF6XpECrY4=; b=o4VYQdQL7cDwFgT/+8RhrsKzzVFqJREdf9jHiIJ4OTS8l2yt5xyqDQjEXKt0hBzkYZ chJJ0zbo9/WVT142aed4j46FrOWstjbwpKSOoGE+csMthutjNBKBK5kacvt9jH9smlpH 4H2SrPVU25H0q3lyxDqLF6rJceRZXjddsCweRRsLnqM5lYxhNLEaAyfXGKKHpt2WdyOI shVj2RyBDdAlxe5AwZageIGOCOedRJQ7v3w6OjHiyMID9NruB1QmKEPtK06x4gzpv3/3 e6dsTTto/YtsFVWGDg+zEhGLPz/6oZSkG6mDFO5tpNZOYFCS93uiWsCNETnvVBMcQXFl UkQA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:date:from:to:cc:subject:message-id :references:mime-version:content-disposition:in-reply-to:user-agent; bh=p0Utk0iWJmN7wGE4iUGfqdM0e+4KevxLcNF6XpECrY4=; b=nB6Sl9Tmk3v5CXPzpvFypc1r+6V7uOwOpGybPX3LDkKH+lDa1rNqpIkAVP4jyyopIR XXeBd2yU2JSp4rbmVTRYzvSzUyKG3FiRQnrZikOrgM7A86dgmLpvang1SjaKrinoR9Cc mIOU2nrGnzDD4B6Nfofg5FmEGI2vUIFQ1NxWWh87GQX/OmNK1t29h9Jzsu2G7tiT8Gde TNO5e6ujsfpvHJJ9wIGWtIbDBP1XCnDgaFqrUyPANcQVot8UoIkU2p50Pe/oSMOQXEqt JBJyj9lpLYRc7Edq1DpJeW+1ufne8XNHy4u4AE99eeEXYgDjGuodtT4RV3krx9HJN0zw HBiQ== X-Gm-Message-State: APjAAAUfvXHZoyph7bHaa2w5j+/+B3yPKKX1VK+9WBuVsAZPLBvfGrIp dQHskmzBP+S6V0o3zXw1CM4RJ7tn X-Google-Smtp-Source: APXvYqyVPNdoxbSG3OzFWoJPxtQz9AwM4IdvDyzeDxHnkKYOZ04XulvUKVNlu1Ji6wHSOx/bRrejSw== X-Received: by 2002:a6b:3b03:: with SMTP id i3mr1288600ioa.302.1561596318465; Wed, 26 Jun 2019 17:45:18 -0700 (PDT) Received: from raichu (toroon0560w-lp140-05-70-29-85-38.dsl.bell.ca. [70.29.85.38]) by smtp.gmail.com with ESMTPSA id v26sm397714iom.88.2019.06.26.17.45.17 (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Wed, 26 Jun 2019 17:45:17 -0700 (PDT) Sender: Mark Johnston Date: Wed, 26 Jun 2019 20:45:15 -0400 From: Mark Johnston To: freebsd-hackers@freebsd.org Cc: re@freebsd.org Subject: Re: release notes file Message-ID: <20190627004515.GB73130@raichu> References: <20190623191818.GA84365@raichu> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190623191818.GA84365@raichu> User-Agent: Mutt/1.12.0 (2019-05-25) X-Rspamd-Queue-Id: A6FB48E5F4 X-Spamd-Bar: ----- Authentication-Results: mx1.freebsd.org; dkim=pass header.d=gmail.com header.s=20161025 header.b=o4VYQdQL; spf=pass (mx1.freebsd.org: domain of markjdb@gmail.com designates 2607:f8b0:4864:20::d33 as permitted sender) smtp.mailfrom=markjdb@gmail.com X-Spamd-Result: default: False [-5.45 / 15.00]; ARC_NA(0.00)[]; RCVD_VIA_SMTP_AUTH(0.00)[]; R_DKIM_ALLOW(-0.20)[gmail.com:s=20161025]; NEURAL_HAM_MEDIUM(-1.00)[-1.000,0]; FROM_HAS_DN(0.00)[]; R_SPF_ALLOW(-0.20)[+ip6:2607:f8b0:4000::/36]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[text/plain]; TO_DN_NONE(0.00)[]; DMARC_NA(0.00)[freebsd.org]; NEURAL_HAM_LONG(-1.00)[-1.000,0]; RCVD_COUNT_THREE(0.00)[3]; RCVD_TLS_LAST(0.00)[]; DKIM_TRACE(0.00)[gmail.com:+]; RCPT_COUNT_TWO(0.00)[2]; RCVD_IN_DNSWL_NONE(0.00)[3.3.d.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.0.4.6.8.4.0.b.8.f.7.0.6.2.list.dnswl.org : 127.0.5.0]; MX_GOOD(-0.01)[cached: alt3.gmail-smtp-in.l.google.com]; NEURAL_HAM_SHORT(-0.99)[-0.993,0]; IP_SCORE(-2.74)[ip: (-8.18), ipnet: 2607:f8b0::/32(-3.14), asn: 15169(-2.34), country: US(-0.06)]; FORGED_SENDER(0.30)[markj@freebsd.org,markjdb@gmail.com]; MIME_TRACE(0.00)[0:+]; MID_RHS_NOT_FQDN(0.50)[]; FREEMAIL_ENVFROM(0.00)[gmail.com]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US]; FROM_NEQ_ENVFROM(0.00)[markj@freebsd.org,markjdb@gmail.com] X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 27 Jun 2019 00:45:20 -0000 On Sun, Jun 23, 2019 at 03:18:18PM -0400, Mark Johnston wrote: > Hi, > > Today we add a Relnotes tag to commits that warrant a release note. > My impression is that it doesn't work so well: if a committer forgets > or doesn't know to add one there's no way to amend the commit message > (same for MFCs), and a commit message isn't a convenient place to write > the text of a release note. I would like to propose adding a top-level > RELNOTES file instead, which like UPDATING would document notes for > specific commits. It would be truncated every time the head branch is > forked, and changes to it would be MFCed. This fixes the > above-mentioned problems and would hopefully reduce the amount of time > needed by re@ to compile release notes. To be clear, my aim here is to help ensure that new features are documented close to when they are committed. Today, release notes are compiled only shortly before a release, which means that re@ has to go through all of the new commits looking for relnotes tags and hope that they didn't miss anything. A RELNOTES file helps prevent things from falling through the cracks and reduces the amount of work required of re@. > For example: > > Index: RELNOTES > =================================================================== > --- RELNOTES (nonexistent) > +++ RELNOTES (working copy) > @@ -0,0 +1,8 @@ > +Release notes for FreeBSD 13.0. > + > +r349286: > + swapon(8) can now erase a swap device immediately before > + enabling it, similar to newfs(8)'s -E option. This behaviour > + can be specified by adding -E to swapon(8)'s command-line > + parameters, or by adding the "trimonce" option to a swap > + device's /etc/fstab entry. > > What do folks think? To summarize what I think are the important points from the discussion that ensued: - RELNOTES would be useful. In other words, I didn't see any opposition to the idea. - It's not clear when and how RELNOTES should be truncated. Since this is really an re@ policy question, it doesn't block RELNOTES from being added to the tree. So, I will ignore this issue and let them figure it out once we actually come up to the next release and have some experience. - It's not clear how best to handle MFCs of RELNOTES. I will propose that we simply not MFC RELNOTES for now: given head's copy of RELNOTES, one can easily determine whether any of the referenced revisions are in a stable branch. - RELNOTES should be easy to parse. - RELNOTES is not intended to be presented directly to users; it is a log that can be used to generate user-friendlier documentation. So, it will not be installed and entries should be in plain text. - (Not actually discussed, but my own thoughts:) There is some overlap with UPDATING; some things that I would consider release notes are documented there. As I understand it, the goal of UPDATING is to document changes that may trip up users who build from source: KBI changes, renames, removals, and so on. RELNOTES is for users of binary FreeBSD releases. So, there may be some overlap, but in general I think we should avoid using UPDATING to document routine changes like contrib/ updates. I put a proposed initial version here: https://reviews.freebsd.org/D20762