From owner-freebsd-hackers@freebsd.org Mon Jun 24 00:36:25 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 49F0215B87EF for ; Mon, 24 Jun 2019 00:36:25 +0000 (UTC) (envelope-from markjdb@gmail.com) Received: from mail-io1-xd32.google.com (mail-io1-xd32.google.com [IPv6:2607:f8b0:4864:20::d32]) (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 5851176624; Mon, 24 Jun 2019 00:36:24 +0000 (UTC) (envelope-from markjdb@gmail.com) Received: by mail-io1-xd32.google.com with SMTP id r185so61663iod.6; Sun, 23 Jun 2019 17:36:24 -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=OEXw2HROMAFEGIywKLpN5rtKpvBwp2QU1MJKol63ZqY=; b=ihgoELl8fRJWhPFGacZe46c9xpJwlmlAupMFrK/OxDzgZPDbkBwBAFLxI0lH8E74W1 lBaONJKQIEZsylr8aPv+2WjK1pT6qKK8aHx/U6nj4L1EeZZZpfSm2AY+jQB/8qwdiMqe jJFLrlvu8BWxyFHl8Oh3TSSbXeWl2q4ows0Pa4k6CCw3DbeE+ZNd13ZMw60qoav/62Oi 9vt0ZocbIJYFegXGwDVednhFhDTAaeiqZPUTIdjPVt0opODKu60Gv5U+ZqvhlLzQTbRI rUWlXpUPxLjy5qitdKF1h227AUaGmxoToCsUWbYRM+jEkqfs7KZWgdgBEz+C8nduMXWP QPxQ== 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=OEXw2HROMAFEGIywKLpN5rtKpvBwp2QU1MJKol63ZqY=; b=lUqFd/2At7s0MwyW5d/XtVbWAwIYfNPSuBylpejTY+s/b+CHSr5n7mW48XgGW4OF3D cO74m7HVYZS1K6JEfbzrtF0x7ZINk9eq8CY15BqAn2TsZIk3cSI2r2jnweUzi3sWq+uu fLBEW/tuaMZM6QzXlWacv2AX0u3osOtHzdwBs8g8UPRcE3w8tJcbCyrp4ajZs3XHE/qF i1p3xxxjKS1KN3bQXy3g6jCoyb2Doc2Osl0kVSeyb0YUXoZjQXB9wFhqvj4GlUPfr5dQ fKAuXX/VfcBwqkaM6e9Hr2SS/OQ0Ki5dvTq5szr5PR2v9RTN8qvrdaBzDkZbInN5NwMh qMZA== X-Gm-Message-State: APjAAAUqbYvYELQjQaT2rXfX7gtyeaV+Ub1YV9NaZabiAi/VKDgre2/b ROU03WJotqZteJx1GvRkrIpNUJce X-Google-Smtp-Source: APXvYqwrUCYqbF8G1HNnC//aMwEGiSVHxbiug2c3yeBboNbznp/gCxEQx5YcuItZFtymGTGxp4JH1g== X-Received: by 2002:a5d:8253:: with SMTP id n19mr14105133ioo.80.1561336582890; Sun, 23 Jun 2019 17:36:22 -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 p10sm14846155iob.54.2019.06.23.17.36.20 (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Sun, 23 Jun 2019 17:36:20 -0700 (PDT) Sender: Mark Johnston Date: Sun, 23 Jun 2019 20:36:16 -0400 From: Mark Johnston To: "Bjoern A. Zeeb" Cc: freebsd-hackers@freebsd.org, re@freebsd.org Subject: Re: release notes file Message-ID: <20190624003616.GA90409@raichu> References: <20190623191818.GA84365@raichu> <55030704-F521-4D6E-9B56-4B7F65EFFC38@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <55030704-F521-4D6E-9B56-4B7F65EFFC38@FreeBSD.org> User-Agent: Mutt/1.12.0 (2019-05-25) X-Rspamd-Queue-Id: 5851176624 X-Spamd-Bar: ----- Authentication-Results: mx1.freebsd.org; dkim=pass header.d=gmail.com header.s=20161025 header.b=ihgoELl8; spf=pass (mx1.freebsd.org: domain of markjdb@gmail.com designates 2607:f8b0:4864:20::d32 as permitted sender) smtp.mailfrom=markjdb@gmail.com X-Spamd-Result: default: False [-5.40 / 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)[]; RCPT_COUNT_THREE(0.00)[3]; R_SPF_ALLOW(-0.20)[+ip6:2607:f8b0:4000::/36]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[text/plain]; MIME_TRACE(0.00)[0:+]; DMARC_NA(0.00)[freebsd.org]; TO_DN_SOME(0.00)[]; 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:+]; MX_GOOD(-0.01)[cached: alt3.gmail-smtp-in.l.google.com]; RCVD_IN_DNSWL_NONE(0.00)[2.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]; NEURAL_HAM_SHORT(-0.90)[-0.897,0]; IP_SCORE(-2.79)[ip: (-8.43), ipnet: 2607:f8b0::/32(-3.14), asn: 15169(-2.33), country: US(-0.06)]; FORGED_SENDER(0.30)[markj@freebsd.org,markjdb@gmail.com]; 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: Mon, 24 Jun 2019 00:36:25 -0000 On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A. Zeeb wrote: > On 23 Jun 2019, at 19:18, 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. > > Hooray. Can we put that file into the doc repo, so that the ports > people, and the docs people, and all other kinds of hats can put things > in there as well? Virtually all of the 12.0 release notes are for src/ (there are 4 lines for ports/pkg and 1 line for docs, and the latter describes a new man page in src). Why is it important to have a single place for everyone to commit their entries? > Oh, the release notes go into the doc repo anyway. Can we just put them > in the right place and just fill them from a skeleton where they should > be and naturally grow the document (feel free to use a different markup > language once doc is ready for that). > > Oh, with that release notes are written automatically and you are still > responsible for that your stuff is in there. And the release notes only > need an editing pass in the end? > > And the wiki pages like “What’s cooking for 13?” or similar could > just vanish as we’d have these updated at least every 10 minutes > automatically .. on our web server under /releases/ where they belong .. > > How amazing would that be? I would guess that many src committers simply won't add release notes if they have to commit to a second repository and use some unfamiliar markup format and worry about validating the file. There are lots of __FreeBSD_version bumps that go undocumented until someone else goes in and fills in the missing entries. A plain-text file in src repo for src release notes is low-friction and creates only marginally more work for RE. "What's cooking for 13?" can just point to the copy of RELNOTES in svnweb. That said, I personally would try to commit my release notes to a doc repo file if one existed. I've spent a few minutes trying to compile the 12.0 notes on my desktop and have not been able to get past, "cannot parse http://www.FreeBSD.org/XML/share/xml/freebsd-xhtml-release.xsl". So, I'm probably not a good person to set up release notes for 13.0. I will help fill in entries for commits since the 12.0 if someone else does that setup.