From owner-freebsd-hackers@freebsd.org Sun Jun 23 21:10:05 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 D3EA715DB604 for ; Sun, 23 Jun 2019 21:10:04 +0000 (UTC) (envelope-from markjdb@gmail.com) Received: from mail-io1-xd2f.google.com (mail-io1-xd2f.google.com [IPv6:2607:f8b0:4864:20::d2f]) (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 C97A670091; Sun, 23 Jun 2019 21:10:03 +0000 (UTC) (envelope-from markjdb@gmail.com) Received: by mail-io1-xd2f.google.com with SMTP id m24so32823ioo.2; Sun, 23 Jun 2019 14:10:03 -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:content-transfer-encoding:in-reply-to :user-agent; bh=NbP/MyeLTeQVGx9cH3fcwmmf3Z1gwQjq0MASQUrhusc=; b=okPerVyIU+NI42vu9zcCLGR/yrtEBWRo4QkD2YzzjRw/zOmerDHVWP2vw96L2YnLbu V+fA4VMm2gJdzYy8QI7qwrdrV5esfEAsnK4K+MmU9x46BBqmb56NcFZVXLcF7ich/Dn7 oF2Sww2p6v/5/oW7EUADAnaPB6rRwDv1oWrthRcYBORwJU2WqY9cThiS+Unz0q/e9BXg h51YU/oZW5ccyXAEJECmcCxaQtLiwjf6lAhq+vCSsMVG9I73o9fp/8cdENP1bJdgA9ci +gJcswN1W2hjpXsiUzxJnlBlYl/o3CoZnwcWh0AAWIRSAY7iYhdCjdvpV9T14Eqy7iPk KQIg== 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 :content-transfer-encoding:in-reply-to:user-agent; bh=NbP/MyeLTeQVGx9cH3fcwmmf3Z1gwQjq0MASQUrhusc=; b=LD4B8hkVGy7ZZ5m/pgGVSrkHcNaNVGZamRNye/DMOFbbObDjz6nkFfM53Y9dv1MkLQ j668/479DQrulbC59zLYRhb3CikBRHePyyZcmsvJBkmyKbuogUn6PqHvyv/yb++UdZrO /FnI8EMk/3C06k4C580xt1peXjccCZD54A7nl7jRQzk9ldUNM/wEClUE3cTv992WEtde mpmODiNmLgfipA5pBXwgTfT2n2lvRXezdBjdoBBivYkY1E0YhrhB6sOxGFQ3C5eIqdt3 cm6Zqiaxu2kjtxS+/EdNLJUBOQgfsfId91bzfcn3PDBCG9TP/Mxaj2j+kynL8KQhPqaX 5KiA== X-Gm-Message-State: APjAAAURU7+cg3KcplaA7bwJgj6CzdOQjclYbKK9KuOe9P5v9P7KksDw kQwBTZHRnDbtdtInkSRAZhyWaAhp X-Google-Smtp-Source: APXvYqzp62cUGWd9r89zYbahDGPETo0NQc6rm2/0yT7fa6ymULEw5rMVvyuiPLaPowrw+NWp3fxSxA== X-Received: by 2002:a02:1948:: with SMTP id b69mr21448030jab.55.1561324202667; Sun, 23 Jun 2019 14:10:02 -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 u26sm11121526iol.1.2019.06.23.14.10.01 (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Sun, 23 Jun 2019 14:10:01 -0700 (PDT) Sender: Mark Johnston Date: Sun, 23 Jun 2019 17:09:59 -0400 From: Mark Johnston To: Glen Barber Cc: Warner Losh , "freebsd-hackers@freebsd.org" , FreeBSD Release Engineering Team Subject: Re: release notes file Message-ID: <20190623210959.GB50070@raichu> References: <20190623191818.GA84365@raichu> <6B485E5C-9C8A-43C8-BD5A-528A74A61A23@FreeBSD.org> <79B7AEEE-7617-44D8-A16A-C8EC5F95455A@FreeBSD.org> <20190623201943.GB41944@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20190623201943.GB41944@FreeBSD.org> User-Agent: Mutt/1.12.0 (2019-05-25) X-Rspamd-Queue-Id: C97A670091 X-Spamd-Bar: ----- Authentication-Results: mx1.freebsd.org; dkim=pass header.d=gmail.com header.s=20161025 header.b=okPerVyI; spf=pass (mx1.freebsd.org: domain of markjdb@gmail.com designates 2607:f8b0:4864:20::d2f as permitted sender) smtp.mailfrom=markjdb@gmail.com X-Spamd-Result: default: False [-5.38 / 15.00]; TO_DN_EQ_ADDR_SOME(0.00)[]; RCVD_VIA_SMTP_AUTH(0.00)[]; TO_DN_SOME(0.00)[]; R_SPF_ALLOW(-0.20)[+ip6:2607:f8b0:4000::/36]; RCVD_COUNT_THREE(0.00)[3]; DKIM_TRACE(0.00)[gmail.com:+]; MX_GOOD(-0.01)[cached: alt3.gmail-smtp-in.l.google.com]; NEURAL_HAM_SHORT(-0.82)[-0.818,0]; FORGED_SENDER(0.30)[markj@freebsd.org,markjdb@gmail.com]; MIME_TRACE(0.00)[0:+]; RCVD_TLS_LAST(0.00)[]; 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]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000,0]; R_DKIM_ALLOW(-0.20)[gmail.com:s=20161025]; FROM_HAS_DN(0.00)[]; RCPT_COUNT_THREE(0.00)[4]; NEURAL_HAM_LONG(-1.00)[-1.000,0]; MIME_GOOD(-0.10)[text/plain]; DMARC_NA(0.00)[freebsd.org]; TO_MATCH_ENVRCPT_SOME(0.00)[]; RCVD_IN_DNSWL_NONE(0.00)[f.2.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]; IP_SCORE(-2.86)[ip: (-8.76), ipnet: 2607:f8b0::/32(-3.14), asn: 15169(-2.33), country: US(-0.06)]; MID_RHS_NOT_FQDN(0.50)[] 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: Sun, 23 Jun 2019 21:10:05 -0000 On Sun, Jun 23, 2019 at 08:19:43PM +0000, Glen Barber wrote: > On Sun, Jun 23, 2019 at 02:01:31PM -0600, Warner Losh wrote: > > On Sun, Jun 23, 2019 at 1:56 PM Glen Barber wrote: > > > > > FWIW, I don’t think “either/or” is necessarily the best approach; meaning > > > I would like to still keep the tag in the default template. > > > > > > > A while ago, I proposed a protocol that we'd only have the RELNOTES file. > > > > The other part of the protocol was to remove it from RELNOTES once it was > > added to the release notes. This way, we can have multiple people working > > on the release notes should we be so fortunate to have those resources in > > the future. It's minorly racy, but not terrible. This way, release notes > > text could also be written by the committer and tweaked by whomever > > compiles the release notes. > > > > However, I'm cool with having it in the commit message + template since > > it's better to have a heads up you need to write something than not. The > > understanding would be a RelNotes: yes would mean that someone else would > > write the notes and if you wanted to have more control over what went out, > > you'd use RELNOTES. > > > > Glen, do you think that's a workable protocol? > > > > It's kind of difficult for me to put the words together that effectively > conveys what I'm thinking or where my mindset is here, but I'll try. > > I am in full support of a RELNOTES file, but I think that should be > supplementary to the 'Relnotes: yes' (or other variations of a non-empty > tag). > > I am conflicted on removing entries from a RELNOTES file once they are > added to the release notes, because that might be a more convenient way > for end users to get an idea of what changed. However, "Relnotes: yes" > does not solve this for those folks. > > It is easy to truncate the file when a new branch is created, just as > a workflow example, but I think the larger thing here is that while > there are folks that commit something without "Relnotes: yes" because > they forgot (or it did not occur to them at the time that it is > a user-visible change), it can be equally difficult to remember to > update a file specifically dedicated to this. > > All that said, having at least a sample text of what to include would be > extremely helpful, at least for me, as sometimes I have to ping > committers out-of-band to understand why a particular commit was flagged > as "Relnotes: yes". > > Hopefully all that made sense. :) It makes sense to me. I think the idea is that "Relnotes: yes" is advisory and serves as a reminder that the commit should get a release note; committers may forget or not want to write RELNOTES entries for some reason. Similar to how "MFC after" is advisory and doesn't guarantee that an MFC has been done after any particular point. re@ would need to scan commits for Relnotes tags that don't have entries in RELNOTES. Since RELNOTES can be updated after the fact, this set would hopefully be small. Regarding whether RELNOTES entries should be removed, I would prefer to keep them at least until head is branched. They would serve as useful documentation to users, and if there are multiple people compiling release notes they can synchronize in other ways. At least, I would wait for it to become a problem before trying to solve it by removing entries from RELNOTES.